2.4. Modifying a Running Standalone Broker's XML Configuration
Abstract
A select set of properties in a standalone Red Hat AMQ 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 factoryYou 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.ImportantIf you fail to disable the OSGi service factory, it will override theruntimeConfigurationPlugin
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 configurationTo enable dynamic runtime configuration, you must set two values in the broker's
.xml
configuration file:- In the
<broker.../>
element, addstart="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 ofcheckPeriod
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.NoteThe unit of value forcheckPeriod
is milliseconds. The default is0
, 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.
Attribute | Type | Queues | Topics |
---|---|---|---|
allConsumersBeforeDispatchStarts | boolean | Y | N |
alwaysRetroactive | boolean | Y | N |
advisoryForConsumed | boolean | Y | N |
advisoryForDelivery | boolean | Y | N |
advisoryForDiscardingMessages | boolean | Y | N |
advisoryForFastProducers | boolean | Y | N |
advisoryForSlowConsumers | boolean | Y | N |
advisoryWhenFull | boolean | Y | N |
blockedProducerWarningInterval | long | Y | N |
consumersBeforeDispatchStarts | int | Y | N |
cursorMemoryHighWaterMark | int | Y | N |
doOptimizeMessageStore | boolean | Y | N |
gcIsInactiveDestinations | boolean | Y | N |
gcWithNetworkConsumers | boolean | Y | N |
inactiveTimeoutBeforeGC | long | Y | N |
lazyDispatch | boolean | Y | Y |
maxBrowsePageSize | int | Y | N |
maxExpirePageSize | int | Y | N |
maxPageSize | int | Y | N |
memoryLimit | string | Y | Y |
minimumMessageSize | long | Y | N |
optimizedDispatch | boolean | Y | N |
optimizeMessageStoreInFlightLimit | int | Y | N |
producerFlowControl | boolean | Y | N |
reduceMemoryFootprint | boolean | Y | N |
sendAdvisoryIfNoConsumers | boolean | Y | N |
storeUsageHighWaterMark | int | Y | N |
strictOrderDispatch | boolean | Y | N |
timeBeforeDispatchStarts | int | Y | N |
useConsumerPriority | boolean | Y | N |
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.NoteThe 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" /> ...