2.4. Modifying a Running Standalone Broker's XML Configuration

Abstract

A select set of properties in a standalone Red Hat JBoss A-MQ message broker's .xml configuration file can be modified, saved, then applied while the broker is running. This dynamic runtime configuration feature is useful when you cannot disrupt the operation of existing producers or consumers with a broker restart.
Important
Take care when using this dynamic runtime configuration feature in production environments as only the xml is validated, and changes to the broker's configuration take effect according to the specified time interval.

Overview

You can edit a running broker's .xml configuration file (default is etc/activemq.xml) directly using an external text or xml editor. Once the edits are saved, the runtime configuration plugin, which monitors the broker's .xml configuration file, applies any detected runtime-supported changes to the running broker. These changes persist through broker restarts.
You can dynamically change only a select set of properties by editing the broker's .xml configuration file:
  • network connectors—add a network connector to a broker or modify the attributes of an existing one
  • virtual destinations—add a virtual destination to a broker or modify the attributes of an existing one
  • destination policy—add a subset of <policyEntry> attributes
  • authorization roles—add or modify roles that define read/write/admin access to queues and topics.

Prerequisites

  • Disable configuration monitoring by the OSGi service factory
    You need to prevent the OSGi service factory from restarting the broker when it detects a change in the broker's configuration. To do so, you edit the installDir/etc/io.fabric8.mq.fabric.server-broker.cfg file to add the line config.check=false.
    Important
    If you fail to disable the OSGi service factory, it will override the runtimeConfigurationPlugin and restart the broker when it detects a change.
    If the broker is stopped, you can edit this file directly using an external text or xml editor. If the broker is running, you must use the appropriate config: shell commands to edit this file.
  • Enable dynamic runtime configuration
    To enable dynamic runtime configuration, you must set two values in the broker's .xml configuration file:
    • In the <broker.../> element, add start="false"; for example:
      <broker xmlns="http://activemq.apache.org//schema/core" ... start="false".../>
      This setting prevents Spring from starting the broker when the spring context is loaded. If Spring starts the broker, the broker will not know the location of the resource that created it, leaving the runtime configuration plugin with nothing to monitor.
    • In the <plugins> element, add <runtimeConfigurationPlugin checkPeriod="1000"> to enable automated runtime configuration; for example:
      <plugins>
  <runtimeConfigurationPlugin checkPeriod="1000" />
</plugins>
      The runtime configuration plugin monitors the broker's .xml configuration file at intervals of checkPeriod and applies only the runtime-supported changes that it detects to the running broker. Modifications made to the attributes of other properties in the broker's .xml configuration file are ignored until the next broker restart.
      Note
      The unit of value for checkPeriod is milliseconds. The default is 0, which disables checking for changes. Using the default, you must manually trigger updates via JMX.

Dynamically updating network connectors

To dynamically update the broker's network connectors, you add a network connector or modify attributes in an existing network connector in the <networkConnectors> section of the broker's .xml configuration file.
For example:
<networkConnectors>
  <networkConnector uri="static:(tcp://localhost:5555)" networkTTL="1" name="one" ... />
</networkConnectors>

Dynamically updating virtual destinations

To dynamically update the broker's virtual destinations, you add a virtual destination or modify attributes in an existing virtual topic in the <destinationInterceptors> section of the broker's .xml configuration file.
For example:
<destinationInterceptors>
  <virtualDestinationInterceptor>
    <virtualDestinations>
      <virtualTopic name="B.>" selector="false" />
    </virtualDestinations>
  </virtualDestinationInterceptor>
</destinationInterceptors>
Note
Changes take effect the next time a new consumer destination is added, not at the runtime configuration plugin's checkPeriod interval.
Note
Out-of-the-box, virtual topics are enabled by default in the broker, without explicit configuration in its .xml configuration file. The first time you add a virtual destination, you must add the entire <destinationInterceptors> section to the broker's .xml configuration file. Doing so replaces the broker's default <destinationInterceptors> configuration.

Dynamically updating the destination policy

To dynamically update the broker's virtual destination policy, you edit the <destinationInterceptors> section in the broker's .xml configuration file.
Table 2.1 lists the runtime-changeable attributes of the <policyEntry> element, which apply to queues and topics.

Table 2.1. Dynamically changeable <policyEntry> attributes

AttributeTypeQueuesTopics
allConsumersBeforeDispatchStartsbooleanYN
alwaysRetroactivebooleanYN
advisoryForConsumedbooleanYN
advisoryForDeliverybooleanYN
advisoryForDiscardingMessagesbooleanYN
advisoryForFastProducersbooleanYN
advisoryForSlowConsumersbooleanYN
advisoryWhenFullbooleanYN
blockedProducerWarningIntervallongYN
consumersBeforeDispatchStartsintYN
cursorMemoryHighWaterMarkintYN
doOptimizeMessageStorebooleanYN
gcIsInactiveDestinationsbooleanYN
gcWithNetworkConsumersbooleanYN
inactiveTimeoutBeforeGClongYN
lazyDispatchbooleanYY
maxBrowsePageSizeintYN
maxExpirePageSizeintYN
maxPageSizeintYN
memoryLimitstringYY
minimumMessageSizelongYN
optimizedDispatchbooleanYN
optimizeMessageStoreInFlightLimitintYN
producerFlowControlbooleanYN
reduceMemoryFootprintbooleanYN
sendAdvisoryIfNoConsumersbooleanYN
storeUsageHighWaterMarkintYN
strictOrderDispatchbooleanYN
timeBeforeDispatchStartsintYN
useConsumerPrioritybooleanYN

Destination policies to control paging

The following destination policies control message paging (the number of messages that are pulled into memory from the message store, each time the memory is emptied):
maxPageSize
The maximum number of messages paged into memory for sending to a destination.
maxBrowsePageSize
The maximum number of messages paged into memory for browsing a queue.
Note
The number of messages paged in for browsing cannot exceed the destination's memoryLimit setting.
maxExpirePageSize
The maximum number of messages paged into memory to check for expired messages.

Dynamically updating authorization roles

To dynamically add authorization roles for accessing the broker's queues and topics, you:
  • add the authorization plugin to the <plugins> section of the broker's .xml configuration file
  • configure the authorization plugin's <map> element
For example:
<plugins>
  <runtimeConfigurationPlugin checkPeriod="1000" />
  <authorizationPlugin>
    <map>
      <authorizationMap>
        <authorizationEntries>
          <authorizationEntry queue=">" read="admins" write="admins" admin="admins" />
          <authorizationEntry queue="USERS.>" read="users" write="users" admin="users" />
          
          <authorizationEntry topic=">" read="admins" write="admins" admin="admins" />
          <authorizationEntry topic="USERS.>" read="users" write="users" admin="users" />
          ...