Configuration Reference

This section is a quick index for looking up configuration. Click on the element name to go to the specific chapter.

Broker Configuration

broker.xml

This is the main core server configuration file which contains the core element. The core element contains the main server configuration.

Modularising broker.xml

XML XInclude support is provided in broker.xml so that you can break your configuration out into separate files.

To do this ensure the following is defined at the root configuration element.

  1. xmlns:xi="http://www.w3.org/2001/XInclude"

You can now define include tag’s where you want to bring in xml configuration from another file:

  1. <xi:include href="my-address-settings.xml"/>

You should ensure xml elements in separated files should be namespaced correctly for example if address-settings element was separated, it should have the element namespace defined:

  1. <address-settings xmlns="urn:activemq:core">

An example can of this feature can be seen in the test suites:

  1. ./artemis-server/src/test/resources/ConfigurationTest-xinclude-config.xml

Note: if you use xmllint to validate the XML against the schema you should enable xinclude flag when running.

  1. --xinclude

For further information on XInclude see:

https://www.w3.org/TR/xinclude/

Reloading modular configuration files

Certain changes in broker.xml can be picked up at runtime as discussed in the Configuration Reload chapter. Changes made directly to files which are included in broker.xml via xi:include will not be automatically reloaded. For example, if broker.xml is including my-address-settings.xml and my-address-settings.xml is modified those changes won’t be reloaded automatically. To force a reload in this situation there are 2 main options:

  1. Use the reloadConfiguration management operation on the ActiveMQServerControl.
  2. Update the timestamp on broker.xml using something like the touch command. The next time the broker inspects broker.xml for automatic reload it will see the updated timestamp and trigger a reload of broker.xml and all its included files.

System properties

It is possible to use System properties to replace some of the configuration properties. If you define a System property starting with “brokerconfig.” that will be passed along to Bean Utils and the configuration would be replaced.

To define global-max-size=1000000 using a system property you would have to define this property, for example through java arguments:

  1. java -Dbrokerconfig.globalMaxSize=1000000

You can also change the prefix through the broker.xml by setting:

  1. <system-property-prefix>yourprefix</system-property-prefix>

This is to help you customize artemis on embedded systems.

The core configuration

This describes the root of the XML configuration. You will see here also multiple sub-types listed. For example on the main config you will have bridges and at the list of bridge type we will describe the properties for that configuration.

Warning

The default values listed below are the values which will be used if the configuration parameter is not set either programmatically or via broker.xml. Some of these values are set in the broker.xml which is available out-of-the-box. Any values set in the out-of-the-box configuration will override the default values listed here. Please consult your specific configuration to know which values will actually be used when the broker is running.

NameDescriptionDefault
acceptorsa list of remoting acceptorsn/a
acceptors.acceptorEach acceptor is composed for just an URLn/a
addressesa list of addressesn/a
address-settingsa list of address-settingn/a
allow-failbackShould stop backup on live restart.true
amqp-use-core-subscription-namingIf true uses CORE queue naming convention for AMQP.false
async-connection-execution-enabledIf False delivery would be always asynchronous.true
bindings-directoryThe folder in use for the bindings folderdata/bindings
bridgesa list of core bridgesn/a
ha-policythe HA policy of this servernone
broadcast-groupsa list of broadcast-groupn/a
broker-connectionsa list of amqp-connectionn/a
broker-pluginsa list of broker-pluginsn/a
configuration-file-refresh-periodThe frequency in milliseconds the configuration file is checked for changes5000
check-for-live-serverUsed for a live server to verify if there are other nodes with the same ID on the topologyn/a
cluster-connectionsa list of cluster-connectionn/a
cluster-passwordCluster password. It applies to all cluster configurations.n/a
cluster-userCluster username. It applies to all cluster configurations.n/a
connection-ttl-overrideif set, this will override how long (in ms) to keep a connection alive without receiving a ping. -1 disables this setting.-1
connection-ttl-check-intervalhow often (in ms) to check connections for ttl violation.2000
connectors.connectorThe URL for the connector. This is a listn/a
create-bindings-dirtrue means that the server will create the bindings directory on start up.true
create-journal-dirtrue means that the journal directory will be created.true
discovery-groupsa list of discovery-groupn/a
disk-scan-periodThe interval where the disk is scanned for percentual usage.5000
divertsa list of diverts to usen/a
global-max-sizeThe amount in bytes before all addresses are considered full.Half of the JVM’s -Xmx
graceful-shutdown-enabledtrue means that graceful shutdown is enabled.false
graceful-shutdown-timeoutTimeout on waiting for clients to disconnect before server shutdown.-1
grouping-handlera message grouping handlern/a
id-cache-sizeThe duplicate detection circular cache size.20000
jmx-domainthe JMX domain used to registered MBeans in the MBeanServer.org.apache.activemq
jmx-use-broker-namewhether or not to use the broker name in the JMX properties.true
jmx-management-enabledtrue means that the management API is available via JMX.true
journal-buffer-sizeThe size of the internal buffer on the journal in KB.490KB
journal-buffer-timeoutThe Flush timeout for the journal buffer500000 for ASYNCIO; 3333333 for NIO
journal-compact-min-filesThe minimal number of data files before we can start compacting. Setting this to 0 means compacting is disabled.10
journal-compact-percentageThe percentage of live data on which we consider compacting the journal.30
journal-directorythe directory to store the journal files in.data/journal
node-manager-lock-directorythe directory to store the node manager lock file.same of journal-directory
journal-file-sizethe size (in bytes) of each journal file.10MB
journal-lock-acquisition-timeouthow long (in ms) to wait to acquire a file lock on the journal.-1
journal-max-iothe maximum number of write requests that can be in the ASYNCIO queue at any one time.4096 for ASYNCIO; 1 for NIO; ignored for MAPPED
journal-file-open-timeoutthe length of time in seconds to wait when opening a new journal file before timing out and failing.5
journal-min-fileshow many journal files to pre-create.2
journal-pool-filesThe upper threshold of the journal file pool, -1 means no Limit. The system will create as many files as needed however when reclaiming files it will shrink back to the journal-pool-files-1
journal-sync-non-transactionalif true wait for non transaction data to be synced to the journal before returning response to client.true
journal-sync-transactionalif true wait for transaction data to be synchronized to the journal before returning response to client.true
journal-typethe type of journal to use.ASYNCIO
journal-datasyncIt will use msync/fsync on journal operations.true
large-messages-directorythe directory to store large messages.data/largemessages
log-delegate-factory-class-namedeprecated the name of the factory class to use for log delegation.n/a
management-addressthe name of the management address to send management messages to.activemq.management
management-notification-addressthe name of the address that consumers bind to receive management notifications.activemq.notifications
mask-passwordThis option controls whether passwords in server configuration need be masked. If set to “true” the passwords are masked.false
max-saved-replicated-journals-sizeThis specifies how many times a replicated backup server can restart after moving its files on start. Once there are this number of backup journal files the server will stop permanently after if fails back. -1 Means no Limit; 0 don’t keep a copy at all.2
max-disk-usageThe max percentage of data we should use from disks. The broker will block while the disk is full. Disable by setting -1.90
memory-measure-intervalfrequency to sample JVM memory in ms (or -1 to disable memory sampling).-1
memory-warning-thresholdPercentage of available memory which will trigger a warning log.25
message-counter-enabledtrue means that message counters are enabled.false
message-counter-max-day-historyhow many days to keep message counter history.10
message-counter-sample-periodthe sample period (in ms) to use for message counters.10000
message-expiry-scan-periodhow often (in ms) to scan for expired messages.30000
message-expiry-thread-prioritydeprecated the priority of the thread expiring messages.3
metrics-plugina plugin to export metricsn/a
address-queue-scan-periodhow often (in ms) to scan for addresses & queues that should be removed.30000
namenode name; used in topology notifications if set.n/a
password-codecthe name of the class (and optional configuration properties) used to decode masked passwords. Only valid when mask-password is true.n/a
page-max-concurrent-ioThe max number of concurrent reads allowed on paging.5
page-sync-timeoutThe time in nanoseconds a page will be synced.3333333 for ASYNCIO; journal-buffer-timeout for NIO
read-whole-pageIf true the whole page would be read, otherwise just seek and read while getting message.false
paging-directorythe directory to store paged messages in.data/paging
persist-delivery-count-before-deliveryTrue means that the delivery count is persisted before delivery. False means that this only happens after a message has been cancelled.false
persistence-enabledtrue means that the server will use the file based journal for persistence.true
persist-id-cachetrue means that ID’s are persisted to the journal.true
queuesdeprecated use addressesn/a
remoting-incoming-interceptorsa list of <class-name/> elements with the names of classes to use for intercepting incoming remoting packetsn/a
remoting-outgoing-interceptorsa list of <class-name/> elements with the names of classes to use for intercepting outgoing remoting packetsn/a
resolveProtocolsUse ServiceLoader to load protocol modules.true
resource-limit-settingsa list of resource-limitsn/a
scheduled-thread-pool-max-sizeMaximum number of threads to use for the scheduled thread pool.5
security-enabledtrue means that security is enabled.true
security-invalidation-intervalhow long (in ms) to wait before invalidating the security cache.10000
system-property-prefixPrefix for replacing configuration settings using Bean Utils.n/a
internal-naming-prefixthe prefix used when naming the internal queues and addresses required for implementing certain behaviours.$.activemq.internal
populate-validated-userwhether or not to add the name of the validated user to the messages that user sends.false
security-settingsa list of security-setting.n/a
thread-pool-max-sizeMaximum number of threads to use for the thread pool. -1 means ‘no limits’.30
transaction-timeouthow long (in ms) before a transaction can be removed from the resource manager after create time.300000
transaction-timeout-scan-periodhow often (in ms) to scan for timeout transactions.1000
wild-card-routing-enabledtrue means that the server supports wild card routing.true
network-check-NICthe NIC (Network Interface Controller) to be used on InetAddress.isReachable.n/a
network-check-URL-listthe list of http URIs to be used to validate the network.n/a
network-check-listthe list of pings to be used on ping or InetAddress.isReachable.n/a
network-check-perioda frequency in milliseconds to how often we should check if the network is still up.10000
network-check-timeouta timeout used in milliseconds to be used on the ping.1000
network-check-ping-commandthe command used to oping IPV4 addresses.n/a
network-check-ping6-commandthe command used to oping IPV6 addresses.n/a
critical-analyzerenable or disable the critical analysis.true
critical-analyzer-timeouttimeout used to do the critical analysis.120000 ms
critical-analyzer-check-periodtime used to check the response times.0.5 * critical-analyzer-timeout
critical-analyzer-policyshould the server log, be halted or shutdown upon failures.LOG
resolve-protocolsif true then the broker will make use of any protocol managers that are in available on the classpath, otherwise only the core protocol will be available, unless in embedded mode where users can inject their own protocol managers.true
resource-limit-settingsa list of resource-limit.n/a
server-dump-intervalinterval to log server specific information (e.g. memory usage etc).-1
storethe store type used by the server.n/a
wildcard-addressesparameters to configure wildcard address matching format.n/a

address-setting type

NameDescriptionDefault
matchThe filter to apply to the settingn/a
dead-letter-addressDead letter addressn/a
auto-create-dead-letter-resourcesWhether or not to auto-create dead-letter address and/or queuefalse
dead-letter-queue-prefixPrefix to use for auto-created dead-letter queuesDLQ.
dead-letter-queue-suffixSuffix to use for auto-created dead-letter queues`` (empty)
expiry-addressExpired messages addressn/a
expiry-delayExpiration time override; -1 don’t override-1
redelivery-delayTime to wait before redelivering a message0
redelivery-delay-multiplierMultiplier to apply to the redelivery-delay1.0
redelivery-collision-avoidance-factoran additional factor used to calculate an adjustment to the redelivery-delay (up or down)0.0
max-redelivery-delayMax value for the redelivery-delay10 * redelivery-delay
max-delivery-attemptsNumber of retries before dead letter address10
max-size-bytesMax size a queue can be before invoking address-full-policy-1
max-size-bytes-reject-thresholdUsed with BLOCK, the max size an address can reach before messages are rejected; works in combination with max-size-bytes for AMQP clients only.-1
page-size-bytesSize of each file on page10485760
address-full-policyWhat to do when a queue reaches max-size-bytesPAGE
message-counter-history-day-limitDays to keep message counter data0
last-value-queuedeprecated Queue is a last value queue; see default-last-value-queue insteadfalse
default-last-value-queuelast-value value if none is set on the queuefalse
default-last-value-keylast-value-key value if none is set on the queuenull
default-exclusive-queueexclusive value if none is set on the queuefalse
default-non-destructivenon-destructive value if none is set on the queuefalse
default-consumers-before-dispatchconsumers-before-dispatch value if none is set on the queue0
default-delay-before-dispatchdelay-before-dispatch value if none is set on the queue-1
redistribution-delayTimeout before redistributing values after no consumers-1
send-to-dla-on-no-routeForward messages to DLA when no queues subscribingfalse
slow-consumer-thresholdMin rate of msgs/sec consumed before a consumer is considered “slow”-1
slow-consumer-policyWhat to do when “slow” consumer is detectedNOTIFY
slow-consumer-check-periodHow often to check for “slow” consumers5
auto-create-jms-queuesdeprecated Create JMS queues automatically; see auto-create-queues & auto-create-addressestrue
auto-delete-jms-queuesdeprecated Delete JMS queues automatically; see auto-create-queues & auto-create-addressestrue
auto-create-jms-topicsdeprecated Create JMS topics automatically; see auto-create-queues & auto-create-addressestrue
auto-delete-jms-topicsdeprecated Delete JMS topics automatically; see auto-create-queues & auto-create-addressestrue
auto-create-queuesCreate queues automaticallytrue
auto-delete-queuesDelete auto-created queues automaticallytrue
auto-delete-created-queuesDelete created queues automaticallyfalse
auto-delete-queues-delayDelay for deleting auto-created queues0
auto-delete-queues-message-countMessage count the queue must be at or below before it can be auto deleted0
config-delete-queuesHow to deal with queues deleted from XML at runtimeOFF
auto-create-addressesCreate addresses automaticallytrue
auto-delete-addressesDelete auto-created addresses automaticallytrue
auto-delete-addresses-delayDelay for deleting auto-created addresses0
config-delete-addressesHow to deal with addresses deleted from XML at runtimeOFF
config-delete-divertsHow to deal with diverts deleted from XML at runtimeOFF
management-browse-page-sizeNumber of messages a management resource can browse200
default-purge-on-no-consumerspurge-on-no-consumers value if none is set on the queuefalse
default-max-consumersmax-consumers value if none is set on the queue-1
default-queue-routing-typeRouting type for auto-created queues if the type can’t be otherwise determinedMULTICAST
default-address-routing-typeRouting type for auto-created addresses if the type can’t be otherwise determinedMULTICAST
default-ring-sizeThe ring-size applied to queues without an explicit ring-size configured-1
retroactive-message-countthe number of messages to preserve for future queues created on the matching address0

bridge type

NameDescriptionDefault
nameunique namen/a
queue-namename of queue that this bridge consumes fromn/a
forwarding-addressaddress to forward to. If omitted original address is usedn/a
hawhether this bridge supports fail-overfalse
filteroptional core filter expressionn/a
transformer-class-nameoptional name of transformer classn/a
min-large-message-sizeLimit before message is considered large.100KB
check-periodHow often to check for TTL violation. -1 means disabled.30000
connection-ttlTTL for the Bridge. This should be greater than the ping period.60000
retry-intervalperiod (in ms) between successive retries.2000
retry-interval-multipliermultiplier to apply to successive retry intervals.1
max-retry-intervalLimit to the retry-interval growth.2000
reconnect-attemptsmaximum number of retry attempts.-1 (no limit)
use-duplicate-detectionforward duplicate detection headers?true
confirmation-window-sizenumber of bytes before confirmations are sent.1MB
producer-window-sizeProducer flow control size on the bridge.-1 (disabled)
userUsername for the bridge, the default is the cluster username.n/a
passwordPassword for the bridge, default is the cluster password.n/a
reconnect-attempts-same-nodeNumber of retries before trying another node.10
routing-typehow to set the routing-type on the bridged messagePASS
concurrencyConcurrency of the bridge1

broadcast-group type

NameType
nameunique name
local-bind-addressLocal bind address that the datagram socket is bound to.
local-bind-portLocal port to which the datagram socket is bound to.
group-addressMulticast address to which the data will be broadcast.
group-portUDP port number used for broadcasting.
broadcast-periodPeriod in milliseconds between consecutive broadcasts. Default=2000.
jgroups-fileName of JGroups configuration file.
jgroups-channelName of JGroups Channel.
connector-refThe connector to broadcast.

cluster-connection type

NameDescriptionDefault
nameunique namen/a
addressname of the address this cluster connection applies ton/a
connector-refName of the connector reference to use.n/a
check-periodThe period (in milliseconds) used to check if the cluster connection has failed to receive pings from another server30000
connection-ttlTimeout for TTL.60000
min-large-message-sizeMessages larger than this are considered large-messages.100KB
call-timeoutTime(ms) before giving up on blocked calls.30000
retry-intervalperiod (in ms) between successive retries.500
retry-interval-multipliermultiplier to apply to the retry-interval.1
max-retry-intervalMaximum value for retry-interval.2000
reconnect-attemptsHow many attempts should be made to reconnect after failure.-1
use-duplicate-detectionshould duplicate detection headers be inserted in forwarded messages?true
message-load-balancinghow should messages be load balanced?OFF
max-hopsmaximum number of hops cluster topology is propagated.1
confirmation-window-sizeThe size (in bytes) of the window used for confirming data from the server connected to.1048576
producer-window-sizeFlow Control for the Cluster connection bridge.-1 (disabled)
call-failover-timeoutHow long to wait for a reply if in the middle of a fail-over. -1 means wait forever.-1
notification-intervalhow often the cluster connection will notify the cluster of its existence right after joining the cluster.1000
notification-attemptshow many times this cluster connection will notify the cluster of its existence right after joining the cluster2

discovery-group type

NameDescription
nameunique name
group-addressMulticast IP address of the group to listen on
group-portUDP port number of the multi cast group
jgroups-fileName of a JGroups configuration file. If specified, the server uses JGroups for discovery.
jgroups-channelName of a JGroups Channel. If specified, the server uses the named channel for discovery.
refresh-timeoutPeriod the discovery group waits after receiving the last broadcast from a particular server before removing that servers connector pair entry from its list. Default=10000
local-bind-addresslocal bind address that the datagram socket is bound to
local-bind-portlocal port to which the datagram socket is bound to. Default=-1
initial-wait-timeouttime to wait for an initial broadcast to give us at least one node in the cluster. Default=10000

divert type

NameDescription
nameunique name
transformer-class-namean optional class name of a transformer
exclusivewhether this is an exclusive divert. Default=false
routing-namethe routing name for the divert
addressthe address this divert will divert from
forwarding-addressthe forwarding address for the divert
filteroptional core filter expression
routing-typehow to set the routing-type on the diverted message. Default=STRIP

address type

NameDescription
nameunique namen/a
anycastlist of anycast queues
multicastlist of multicast queues

queue type

NameDescriptionDefault
nameunique namen/a
filteroptional core filter expressionn/a
durablewhether the queue is durable (persistent).true
userthe name of the user to associate with the creation of the queuen/a
max-consumersthe max number of consumers allowed on this queue-1 (no max)
purge-on-no-consumerswhether or not to delete all messages and prevent routing when no consumers are connectedfalse
exclusiveonly deliver messages to one of the connected consumersfalse
last-valueuse last-value semanticsfalse
ring-sizethe size this queue should maintain according to ring semanticsbased on default-ring-size address-setting
consumers-before-dispatchnumber of consumers required before dispatching messages0
delay-before-dispatchmilliseconds to wait for consumers-before-dispatch to be met before dispatching messages anyway-1 (wait forever)

security-setting type

NameDescription
matchaddress expression
permission
permission.typethe type of permission
permission.rolesa comma-separated list of roles to apply the permission to
role-mappingA simple role mapping that can be used to map roles from external authentication providers (i.e. LDAP) to internal roles
role-mapping.fromThe external role which should be mapped
role-mapping.toThe internal role which should be assigned to the authenticated user

broker-plugin type

NameDescription
propertyproperties to configure a plugin
class-namethe name of the broker plugin class to instantiate

metrics-plugin type

NameDescription
propertyproperties to configure a plugin
class-namethe name of the metrics plugin class to instantiate

resource-limit type

NameDescriptionDefault
matchthe name of the user to whom the limits should be appliedn/a
max-connectionshow many connections are allowed by the matched user-1 (no max)
max-queueshow many queues can be created by the matched user-1 (no max)

grouping-handler type

NameDescriptionDefault
nameA unique namen/a
typeLOCAL or REMOTEn/a
addressA reference to a cluster-connection addressn/a
timeoutHow long to wait for a decision5000
group-timeoutHow long a group binding will be used.-1 (disabled)
reaper-periodHow often the reaper will be run to check for timed out group bindings. Only valid for LOCAL handlers.30000

amqp-connection type

NameDescriptionDefault
uriAMQP broker connection URI (required)n/a
nameA unique namen/a
userBroker authentication user (optional)n/a
passwordBroker authentication password (optional)n/a
reconnect-attemptsHow many attempts should be made to reconnect after failure.-1 (infinite)
auto-startBroker connection starts automatically with brokertrue