2.3. Editing a Standalone Broker's Configuration
Abstract
A standalone Red Hat JBoss A-MQ message broker's configuration can be edited by directly modifying the configuration template and using the command console commands.
Overview
A standalone broker is one that is not part of a fabric. A standalone broker can, however, be part of a network of broker, a master/slave cluster, or a failover cluster. The distinction is that a standalone is responsible for managing and storing its own configuration.
All of the configuration changes are made directly on the local instance. You make changes using a combination of edits to local configuration template and commands from the console's config shell. The configuration template must be edited using an external editor. The configuration the control's the behavior of the broker's runtime container is changed using the console commands.
Editing the configuration template
The default broker configuration template is
etc/activemq.xml. You can the location of the configuration template by changing the config property in the broker's etc/io.fabric8.mq.fabric.server-broker.cfg file.
The template can be edited using any text or XML editor.
The broker must be restarted for any changes in the template to take effect.
Splitting activemq.xml into multiple files
For complex broker configurations, you might prefer to split the
etc/activemq.xml file into multiple XML files. You can do this using standard XML entities, declared in a DTD internal subset. For example, say you have an etc/activemq.xml file with the following outline:
<beans ... >
...
<broker xmlns="http://activemq.apache.org/schema/core"
brokerName="${broker-name}"
dataDirectory="${data}"
start="false" restartAllowed="false">
<destinationPolicy>
<policyMap>
<policyEntries>
<policyEntry topic=">" producerFlowControl="true">
<pendingMessageLimitStrategy>
<constantPendingMessageLimitStrategy limit="1000"/>
</pendingMessageLimitStrategy>
</policyEntry>
<policyEntry queue=">" producerFlowControl="true" memoryLimit="1mb">
</policyEntry>
</policyEntries>
</policyMap>
</destinationPolicy>
<!-- Rest of the broker configuration -->
...
</broker>
</beans>
In this example, we assume you want to store the
destinationPolicy element in a separate file. First of all, create a new file, etc/destination-policy.xml, to store the destinationPolicy element, with the following content:
<destinationPolicy>
<policyMap>
<policyEntries>
<policyEntry topic=">" producerFlowControl="true">
<pendingMessageLimitStrategy>
<constantPendingMessageLimitStrategy limit="1000"/>
</pendingMessageLimitStrategy>
</policyEntry>
<policyEntry queue=">" producerFlowControl="true" memoryLimit="1mb">
</policyEntry>
</policyEntries>
</policyMap>
</destinationPolicy>
You can then reference and include the contents of the
etc/destination-policy.xml file in your etc/activemq.xml file by editing activemq.xml, as follows:
<!DOCTYPE beans [ <!ENTITY destinationpolicy SYSTEM "file:etc/destination-policy.xml"> ]> <beans ... > ... <broker xmlns="http://activemq.apache.org/schema/core" brokerName="${broker-name}" dataDirectory="${data}" start="false" restartAllowed="false"> &destinationpolicy; <!-- Rest of the broker configuration --> ... </broker> </beans>
Where the destinationPolicy element has now been replaced by the
&destinationpolicy; entity reference.
If you need to specify the absolute location of the
destination-policy.xml file, use the URL format, file:///path/to/file. For example, to reference the absolute location, /var/destination-policy.xml, you would use the following DOCTYPE declaration at the start of the file:
<!DOCTYPE beans [ <!ENTITY destinationpolicy SYSTEM "file:///var/destination-policy.xml"> ]> ...
Format of the DOCTYPE declaration
The recommended format of the
DOCTYPE declaration to use with the etc/activemq.xml file is as follows:
<!DOCTYPE RootElement [ <!ENTITY EntityName SYSTEM "URL"> ]> ...
Note the following points about this format:
RootElement- This must always match the name of the root element in the current file. In the case of
activemq.xml, the root element isbeans. EntityName- The name of the entity you are defining with this ENTITY declaration. In the main part of the current XML file, you can insert the contents of this entity using the entity reference,
&EntityName;. URL- To store the contents of the entity in a file, you must reference the file using the
file:scheme. Because of the way that ActiveMQ processes the XML file, it is not guaranteed to work, if you leave out thefile:prefix. Relative paths have the formatfile:path/to/fileand absolute paths have the formatfile:///path/to/file.
Editing the OSGi properties
The initial values for all of the OSGi properties configuring the broker are specified in the
etc/io.fabric8.mq.fabric.server-broker.cfg file. You can edit these values using the command console's config shell. The PID for these values are io.fabric8.mq.fabric.server.id. The id is assigned by the container when the broker is started.
In addition to the broker's messaging behavior, a number of the broker's runtime behavior such as logging levels, the Fuse Management Console behavior, and the JMX behavior are controlled by by OSGi properties stored in different PIDs.
To find the value for a broker's id use and the PIDs for the other runtime configuration settings, use the config:list command.
Config shell
The config shell has a series of commands for editing OSGi properties:
- config:list—lists all of the runtime configuration files and the current values for their properties
- config:edit—opens an editing session for a configuration file
- config:propset—changes the value of a configuration property
- config:propdel—deletes a configuration property
- config:update—saves the changes to the configuration file being edited
