14. Miscellaneous - Configuration Index - 《Apache ActiveMQ Artemis v2.36 User Manual》

1. Broker Configuration
2. The core configuration
3. address-setting type
4. bridge type
5. broadcast-group type
6. cluster-connection type
7. discovery-group type
8. divert type
9. address type
10. queue type
11. security-setting type
12. broker-plugin type
13. metrics-plugin type
14. resource-limit type
15. grouping-handler type
16. amqp-connection type

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

1. Broker Configuration

1.1. broker.xml

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

1.1.1. 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.

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:

<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:

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

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

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

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

--xinclude

For further information on XInclude see: https://www.w3.org/TR/xinclude/

To disable XML external entity processing use the system property artemis.disableXxe, e.g.:

-Dartemis.disableXxe=true

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:

Use the reloadConfiguration management operation on the ActiveMQServerControl.
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.

1.2. 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:

java -Dbrokerconfig.globalMaxSize=1000000

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

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

This is to help you customize artemis on embedded systems.

1.3. Broker properties

Broker properties extends the use of properties to allow updates and additions to the broker configuration after any xml has been parsed. In the absence of any broker.xml, the hard coded defaults can be modified. Internally, any xml configuration is applied to a java bean style configuration object. Typically, there are setters for each of the xml attributes. However, for properties, the naming convention changes from ‘a-b’ to ‘aB’ to reflect the camelCase java naming convention.

Collections need some special treatment to allow additions and reference. We utilise the name attribute of configuration entities to find existing entries and when populating new entities, we set the name to match the requested key. Removal of configuration from named collections is supported by setting a key value to “-“. The remove match value can be configured with a property key “remove.value”.

For example, a properties file containing:

securityEnabled=false
acceptorConfigurations.tcp.factoryClassName=org.apache.activemq.artemis.core.remoting.impl.netty.NettyAcceptorFactory
acceptorConfigurations.tcp.params.HOST=localhost
acceptorConfigurations.tcp.params.PORT=61616

would: 1) disable RBAC security checks 2) add or modify an acceptor named “tcp” that will use Netty 3) set the acceptor named “tcp” ‘HOST’ parameter to localhost 4) set the acceptor named “tcp” ‘PORT’ parameter to 61616

The configuration properties are low level, lower level than xml, however it is very powerful; any accessible attribute of the internal org.apache.activemq.artemis.core.config.impl.ConfigurationImpl objects can be modified.

With great power one must take great care!

The artemis run command script supports --properties <properties file url>, where a properties file can be configured.

one shortcoming of this method of configuration is that any property that does not match is ignored with no fanfare. Enable debug logging for org.apache.activemq.artemis.core.config.impl.ConfigurationImpl to get more insight.

There are a growing number of examples of what can be explicitly configured in this way in the unit test.

2. 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.

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.

Name	Description	Default
acceptors	a list of remoting acceptors	n/a
acceptors.acceptor	Each acceptor is composed for just an URL	n/a
addresses	a list of addresses	n/a
address-settings	a list of address-setting	n/a
allow-failback	Should stop backup on primary restart.	`true`
amqp-use-core-subscription-naming	If true uses CORE queue naming convention for AMQP.	`false`
async-connection-execution-enabled	If False delivery would be always asynchronous.	`true`
bindings-directory	The folder in use for the bindings folder	`data/bindings`
bridges	a list of core bridges	n/a
ha-policy	the HA policy of this server	none
broadcast-groups	a list of broadcast-group	n/a
broker-connections	a list of amqp-connection	n/a
broker-plugins	a list of broker-plugins	n/a
configuration-file-refresh-period	The frequency in milliseconds the configuration file is checked for changes	5000
check-for-active-server	Used by a primary server to verify if there are other nodes with the same ID on the topology	n/a
cluster-connections	a list of cluster-connection	n/a
cluster-password	Cluster password. It applies to all cluster configurations.	n/a
cluster-user	Cluster username. It applies to all cluster configurations.	n/a
connection-ttl-override	if 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-interval	how often (in ms) to check connections for ttl violation.	2000
connectors.connector	The URL for the connector. This is a list	n/a
create-bindings-dir	true means that the server will create the bindings directory on start up.	`true`
create-journal-dir	true means that the journal directory will be created.	`true`
discovery-groups	a list of discovery-group	n/a
disk-scan-period	The interval where the disk is scanned for percentual usage.	5000
diverts	a list of diverts to use	n/a
global-max-size	The amount in bytes before all addresses are considered full.	Half of the JVM’s `-Xmx`
graceful-shutdown-enabled	true means that graceful shutdown is enabled.	`false`
graceful-shutdown-timeout	Timeout on waiting for clients to disconnect before server shutdown.	-1
grouping-handler	a message grouping handler	n/a
id-cache-size	The duplicate detection circular cache size.	20000
jmx-domain	the JMX domain used to registered MBeans in the MBeanServer.	`org.apache.activemq`
jmx-use-broker-name	whether or not to use the broker name in the JMX properties.	`true`
jmx-management-enabled	true means that the management API is available via JMX.	`true`
journal-buffer-size	The size of the internal buffer on the journal in KB.	490KB
journal-buffer-timeout	The Flush timeout for the journal buffer	500000 for ASYNCIO; 3333333 for NIO
journal-compact-min-files	The minimal number of data files before we can start compacting. Setting this to 0 means compacting is disabled.	10
journal-compact-percentage	The percentage of live data on which we consider compacting the journal.	30
journal-directory	the directory to store the journal files in.	`data/journal`
node-manager-lock-directory	the directory to store the node manager lock file.	same of `journal-directory`
journal-file-size	the size (in bytes) of each journal file.	10MB
journal-lock-acquisition-timeout	how long (in ms) to wait to acquire a file lock on the journal.	-1
journal-max-io	the 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-timeout	the length of time in seconds to wait when opening a new journal file before timing out and failing.	5
journal-min-files	how many journal files to pre-create.	2
journal-pool-files	The 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-transactional	if true wait for non transaction data to be synced to the journal before returning response to client.	`true`
journal-sync-transactional	if true wait for transaction data to be synchronized to the journal before returning response to client.	`true`
journal-type	the type of journal to use.	`ASYNCIO`
journal-datasync	It will use msync/fsync on journal operations.	`true`
large-messages-directory	the directory to store large messages.	`data/largemessages`
log-delegate-factory-class-name	deprecated the name of the factory class to use for log delegation.	n/a
management-address	the name of the management address to send management messages to.	`activemq.management`
management-notification-address	the name of the address that consumers bind to receive management notifications.	`activemq.notifications`
mask-password	This option controls whether passwords in server configuration need be masked. If set to “true” the passwords are masked.	`false`
max-saved-replicated-journals-size	This specifies how many replication backup directories will be kept when server starts as replica. -1 Means no Limit; 0 don’t keep a copy at all.	2
max-disk-usage	The 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-interval	frequency to sample JVM memory in ms (or -1 to disable memory sampling).	-1
memory-warning-threshold	Percentage of available memory which will trigger a warning log.	25
message-counter-enabled	true means that message counters are enabled.	`false`
message-counter-max-day-history	how many days to keep message counter history.	10
message-counter-sample-period	the sample period (in ms) to use for message counters.	10000
message-expiry-scan-period	how often (in ms) to scan for expired messages.	30000
message-expiry-thread-priority	deprecated the priority of the thread expiring messages.	3
metrics-plugin	a plugin to export metrics	n/a
address-queue-scan-period	how often (in ms) to scan for addresses & queues that should be removed.	30000
name	node name; used in topology notifications if set.	n/a
password-codec	the 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-io	The max number of concurrent reads allowed on paging.	5
page-sync-timeout	The time in nanoseconds a page will be synced.	3333333 for ASYNCIO; `journal-buffer-timeout` for NIO
read-whole-page	If true the whole page would be read, otherwise just seek and read while getting message.	`false`
paging-directory	the directory to store paged messages in.	`data/paging`
persist-delivery-count-before-delivery	True means that the delivery count is persisted before delivery. False means that this only happens after a message has been cancelled.	`false`
max-redelivery-records	Maximum number of records the system will store for redeliveries. In most cases this should be set to ‘1’.	`10`
persistence-enabled	true means that the server will use the file based journal for persistence.	`true`
persist-id-cache	true means that ID’s are persisted to the journal.	`true`
queues	deprecated use addresses	n/a
remoting-incoming-interceptors	a list of <class-name/> elements with the names of classes to use for intercepting incoming remoting packets	n/a
remoting-outgoing-interceptors	a list of <class-name/> elements with the names of classes to use for intercepting outgoing remoting packets	n/a
resolveProtocols	Use ServiceLoader to load protocol modules.	`true`
resource-limit-settings	a list of resource-limits	n/a
scheduled-thread-pool-max-size	Maximum number of threads to use for the scheduled thread pool.	5
security-enabled	true means that security is enabled.	`true`
security-invalidation-interval	how long (in ms) to wait before invalidating the security cache.	10000
system-property-prefix	Prefix for replacing configuration settings using Bean Utils.	n/a
internal-naming-prefix	the prefix used when naming the internal queues and addresses required for implementing certain behaviours.	`$.activemq.internal`
populate-validated-user	whether or not to add the name of the validated user to the messages that user sends.	`false`
security-settings	a list of security-setting.	n/a
thread-pool-max-size	Maximum number of threads to use for the thread pool. -1 means ‘no limits’.	30
transaction-timeout	how long (in ms) before a transaction can be removed from the resource manager after create time.	300000
transaction-timeout-scan-period	how often (in ms) to scan for timeout transactions.	1000
wild-card-routing-enabled	true means that the server supports wild card routing.	`true`
network-check-NIC	the NIC (Network Interface Controller) to be used on InetAddress.isReachable.	n/a
network-check-URL-list	the list of http URIs to be used to validate the network.	n/a
network-check-list	the list of pings to be used on ping or InetAddress.isReachable.	n/a
network-check-period	a frequency in milliseconds to how often we should check if the network is still up.	10000
network-check-timeout	a timeout used in milliseconds to be used on the ping.	1000
network-check-ping-command	the command used to oping IPV4 addresses.	n/a
network-check-ping6-command	the command used to oping IPV6 addresses.	n/a
critical-analyzer	enable or disable the critical analysis.	`true`
critical-analyzer-timeout	timeout used to do the critical analysis.	120000 ms
critical-analyzer-check-period	time used to check the response times.	0.5 `critical-analyzer-timeout`
critical-analyzer-policy	should the server log, be halted or shutdown upon failures.	`LOG`
resolve-protocols	if 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-settings	a list of resource-limit.	n/a
server-dump-interval	interval to log server specific information (e.g. memory usage etc).	-1
store	the store type used by the server.	n/a
wildcard-addresses	parameters to configure wildcard address matching format.	n/a
view-permission-method-match-pattern	parameter to configure the regular expression pattern to match management or JMX operations that require the ‘view’ permission in your security-settings.	`^(get\|is\|count\|list\|browse\|query).$`
management-message-rbac	parameter to enable security-settings RBAC on management messages sent to the management address.	false
management-rbac-prefix	parameter to configure the prefix for security-settings match addresses to control RBAC on JMX MBean operations and optionally on management messages	mops (shorthand for management operations)

3. address-setting type

Name	Description	Default
match	The filter to apply to the setting	n/a
dead-letter-address	Dead letter address	n/a
auto-create-dead-letter-resources	Whether or not to auto-create dead-letter address and/or queue	`false`
dead-letter-queue-prefix	Prefix to use for auto-created dead-letter queues	`DLQ.`
dead-letter-queue-suffix	Suffix to use for auto-created dead-letter queues	`` (empty)
expiry-address	Expired messages address	n/a
expiry-delay	Expiration time override; -1 don’t override	-1
redelivery-delay	Time to wait before redelivering a message	0
redelivery-delay-multiplier	Multiplier to apply to the `redelivery-delay`	1.0
redelivery-collision-avoidance-factor	an additional factor used to calculate an adjustment to the `redelivery-delay` (up or down)	0.0
max-redelivery-delay	Max value for the `redelivery-delay`	10 * `redelivery-delay`
max-delivery-attempts	Number of retries before dead letter address	10
max-size-bytes	Max size a queue can be before invoking `address-full-policy`	-1
max-size-bytes-reject-threshold	Used 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-bytes	Size of each file on page	10485760
address-full-policy	What to do when a queue reaches `max-size-bytes`	`PAGE`
message-counter-history-day-limit	Days to keep message counter data	0
last-value-queue	deprecated Queue is a last value queue; see `default-last-value-queue` instead	`false`
default-last-value-queue	`last-value` value if none is set on the queue	`false`
default-last-value-key	`last-value-key` value if none is set on the queue	`null`
default-exclusive-queue	`exclusive` value if none is set on the queue	`false`
default-non-destructive	`non-destructive` value if none is set on the queue	`false`
default-consumers-before-dispatch	`consumers-before-dispatch` value if none is set on the queue	0
default-delay-before-dispatch	`delay-before-dispatch` value if none is set on the queue	-1
redistribution-delay	Timeout before redistributing values after no consumers	-1
send-to-dla-on-no-route	Forward messages to DLA when no queues subscribing	`false`
slow-consumer-threshold	Min rate of msgs/sec consumed before a consumer is considered “slow”	-1
slow-consumer-policy	What to do when “slow” consumer is detected	`NOTIFY`
slow-consumer-check-period	How often to check for “slow” consumers	5
auto-create-jms-queues	deprecated Create JMS queues automatically; see `auto-create-queues` & `auto-create-addresses`	`true`
auto-delete-jms-queues	deprecated Delete JMS queues automatically; see `auto-create-queues` & `auto-create-addresses`	`true`
auto-create-jms-topics	deprecated Create JMS topics automatically; see `auto-create-queues` & `auto-create-addresses`	`true`
auto-delete-jms-topics	deprecated Delete JMS topics automatically; see `auto-create-queues` & `auto-create-addresses`	`true`
auto-create-queues	Create queues automatically	`true`
auto-delete-queues	Delete auto-created queues automatically	`true`
auto-delete-created-queues	Delete created queues automatically	`false`
auto-delete-queues-delay	Delay for deleting auto-created queues	0
auto-delete-queues-message-count	Message count the queue must be at or below before it can be auto deleted	0
config-delete-queues	How to deal with queues deleted from XML at runtime	`OFF`
auto-create-addresses	Create addresses automatically	`true`
auto-delete-addresses	Delete auto-created addresses automatically	`true`
auto-delete-addresses-delay	Delay for deleting auto-created addresses	0
config-delete-addresses	How to deal with addresses deleted from XML at runtime	`OFF`
config-delete-diverts	How to deal with diverts deleted from XML at runtime	`OFF`
management-browse-page-size	Number of messages a management resource can browse	200
default-purge-on-no-consumers	`purge-on-no-consumers` value if none is set on the queue	`false`
default-max-consumers	`max-consumers` value if none is set on the queue	-1
default-queue-routing-type	Routing type for auto-created queues if the type can’t be otherwise determined	`MULTICAST`
default-address-routing-type	Routing type for auto-created addresses if the type can’t be otherwise determined	`MULTICAST`
default-ring-size	The ring-size applied to queues without an explicit `ring-size` configured	`-1`
retroactive-message-count	the number of messages to preserve for future queues created on the matching address	`0`
id-cache-size	The duplicate detection circular cache size	Inherits from global `id-cache-size`

4. bridge type

Name	Description	Default
name	unique name	n/a
queue-name	name of queue that this bridge consumes from	n/a
forwarding-address	address to forward to. If omitted original address is used	n/a
ha	whether this bridge supports fail-over	`false`
filter	optional core filter expression	n/a
transformer-class-name	optional name of transformer class	n/a
min-large-message-size	Limit before message is considered large.	100KB
check-period	How often to check for TTL violation. -1 means disabled.	30000
connection-ttl	TTL for the Bridge. This should be greater than the ping period.	60000
retry-interval	period (in ms) between successive retries.	2000
retry-interval-multiplier	multiplier to apply to successive retry intervals.	1
max-retry-interval	Limit to the retry-interval growth.	2000
reconnect-attempts	maximum number of retry attempts.	-1 (no limit)
use-duplicate-detection	forward duplicate detection headers?	`true`
confirmation-window-size	number of bytes before confirmations are sent.	1MB
producer-window-size	Producer flow control size on the bridge.	-1 (disabled)
user	Username for the bridge, the default is the cluster username.	n/a
password	Password for the bridge, default is the cluster password.	n/a
reconnect-attempts-same-node	Number of retries before trying another node.	10
routing-type	how to set the routing-type on the bridged message	`PASS`
concurrency	Concurrency of the bridge	1

5. broadcast-group type

Name	Type
name	unique name
local-bind-address	Local bind address that the datagram socket is bound to.
local-bind-port	Local port to which the datagram socket is bound to.
group-address	Multicast address to which the data will be broadcast.
group-port	UDP port number used for broadcasting.
broadcast-period	Period in milliseconds between consecutive broadcasts. Default=2000.
jgroups-file	Name of JGroups configuration file.
jgroups-channel	Name of JGroups Channel.
connector-ref	The `connector` to broadcast.

6. cluster-connection type

Name	Description	Default
name	unique name	n/a
address	name of the address this cluster connection applies to	n/a
connector-ref	Name of the connector reference to use.	n/a
check-period	The period (in milliseconds) used to check if the cluster connection has failed to receive pings from another server	30000
connection-ttl	Timeout for TTL.	60000
min-large-message-size	Messages larger than this are considered large-messages.	100KB
call-timeout	Time(ms) before giving up on blocked calls.	30000
retry-interval	period (in ms) between successive retries.	500
retry-interval-multiplier	multiplier to apply to the retry-interval.	1
max-retry-interval	Maximum value for retry-interval.	2000
reconnect-attempts	How many attempts should be made to reconnect after failure.	-1
use-duplicate-detection	should duplicate detection headers be inserted in forwarded messages?	`true`
message-load-balancing	how should messages be load balanced?	`OFF`
max-hops	maximum number of hops cluster topology is propagated.	1
confirmation-window-size	The size (in bytes) of the window used for confirming data from the server connected to.	1048576
producer-window-size	Flow Control for the Cluster connection bridge.	-1 (disabled)
call-failover-timeout	How long to wait for a reply if in the middle of a fail-over. -1 means wait forever.	-1
notification-interval	how often the cluster connection will notify the cluster of its existence right after joining the cluster.	1000
notification-attempts	how many times this cluster connection will notify the cluster of its existence right after joining the cluster	2

7. discovery-group type

Name	Description
name	unique name
group-address	Multicast IP address of the group to listen on
group-port	UDP port number of the multi cast group
jgroups-file	Name of a JGroups configuration file. If specified, the server uses JGroups for discovery.
jgroups-channel	Name of a JGroups Channel. If specified, the server uses the named channel for discovery.
refresh-timeout	Period 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-address	local bind address that the datagram socket is bound to
local-bind-port	local port to which the datagram socket is bound to. Default=-1
initial-wait-timeout	time to wait for an initial broadcast to give us at least one node in the cluster. Default=10000

8. divert type

Name	Description
name	unique name
transformer-class-name	an optional class name of a transformer
exclusive	whether this is an exclusive divert. Default=false
routing-name	the routing name for the divert
address	the address this divert will divert from
forwarding-address	the forwarding address for the divert
filter	optional core filter expression
routing-type	how to set the routing-type on the diverted message. Default=`STRIP`

9. address type

Name	Description
name	unique name	n/a
anycast	list of anycast queues
multicast	list of multicast queues

10. queue type

Name	Description	Default
name	unique name	n/a
filter	optional core filter expression	n/a
durable	whether the queue is durable (persistent).	`true`
user	the name of the user to associate with the creation of the queue	n/a
max-consumers	the max number of consumers allowed on this queue	-1 (no max)
purge-on-no-consumers	whether or not to delete all messages and prevent routing when no consumers are connected	`false`
exclusive	only deliver messages to one of the connected consumers	`false`
last-value	use last-value semantics	`false`
ring-size	the size this queue should maintain according to ring semantics	based on `default-ring-size` `address-setting`
consumers-before-dispatch	number of consumers required before dispatching messages	0
delay-before-dispatch	milliseconds to wait for `consumers-before-dispatch` to be met before dispatching messages anyway	-1 (wait forever)

11. security-setting type

Name	Description
match	address expression
permission
permission.type	the type of permission
permission.roles	a comma-separated list of roles to apply the permission to
role-mapping	A simple role mapping that can be used to map roles from external authentication providers (i.e. LDAP) to internal roles
role-mapping.from	The external role which should be mapped
role-mapping.to	The internal role which should be assigned to the authenticated user

12. broker-plugin type

Name	Description
property	properties to configure a plugin
class-name	the name of the broker plugin class to instantiate

13. metrics-plugin type

Name	Description
property	properties to configure a plugin
class-name	the name of the metrics plugin class to instantiate

14. resource-limit type

Name	Description	Default
match	the name of the user to whom the limits should be applied	n/a
max-connections	how many connections are allowed by the matched user	-1 (no max)
max-queues	how many queues can be created by the matched user	-1 (no max)

15. grouping-handler type

Name	Description	Default
name	A unique name	n/a
type	`LOCAL` or `REMOTE`	n/a
address	A reference to a `cluster-connection` `address`	n/a
timeout	How long to wait for a decision	5000
group-timeout	How long a group binding will be used.	-1 (disabled)
reaper-period	How often the reaper will be run to check for timed out group bindings. Only valid for `LOCAL` handlers.	30000

16. amqp-connection type

Name	Description	Default
uri	AMQP broker connection URI (required)	n/a
name	A unique name	n/a
user	Broker authentication user (optional)	n/a
password	Broker authentication password (optional)	n/a
reconnect-attempts	How many attempts should be made to reconnect after failure.	-1 (infinite)
auto-start	Broker connection starts automatically with broker	true