activemq-artemis/docs/user-manual/en/configuration-index.md

Configuration Reference

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

Server Configuration

activemq-configuration.xml

This is the main core server configuration file which contains to elements 'core' and 'jms'. The 'core' element contains the main server configuration while the 'jms' element is used by the server side JMS service to load JMS Queues, Topics

The core configuration

Element Name	Element Type	Description	Default
acceptors	Sequence of <acceptor/>	a list of remoting acceptors to create
acceptors.acceptor	Complex element
acceptors.acceptor.name (attribute)	xsd:string	Name of the acceptor
acceptors.acceptor.factory-class	xsd:string	Name of the AcceptorFactory implementation
acceptors.acceptor.param	Complex element	A key-value pair used to configure the acceptor. An acceptor can have many param
acceptors.acceptor.param.key (required attribute)	xsd:string	Key of a configuration parameter
acceptors.acceptor.param.value (required attribute)	xsd:string	Value of a configuration parameter
address-settings	Sequence of <address-setting/>	a list of address settings
address-settings.address-setting	Complex element
address-settings.address-setting.match (required attribute)	xsd:string	XXX
address-settings.address-setting.dead-letter-address	xsd:string	the address to send dead messages to
address-settings.address-setting.expiry-address	xsd:string	the address to send expired messages to
address-settings.address-setting.expiry-delay	xsd:long	Overrides the expiration time for messages using the default value for expiration time. "-1" disables this setting.	-1
address-settings.address-setting.redelivery-delay	xsd:long	the time (in ms) to wait before redelivering a cancelled message.	0
address-settings.address-setting.redelivery-delay-multiplier	xsd:double	multipler to apply to the "redelivery-delay"
address-settings.address-setting.max-redelivery-delay	xsd:long	Maximum value for the redelivery-delay
address-settings.address-setting.max-delivery-attempts	xsd:int	how many times to attempt to deliver a message before sending to dead letter address	10
address-settings.address-setting.max-size-bytes	xsd:long	the maximum size (in bytes) to use in paging for an address (-1 means no limits)	-1
address-settings.address-setting.page-size-bytes	xsd:long	the page size (in bytes) to use for an address	10485760 (10 * 1024 * 1024)
address-settings.address-setting.page-max-cache-size	xsd:int	Number of paging files to cache in memory to avoid IO during paging navigation	5
address-settings.address-setting.address-full-policy	DROP|FAIL|PAGE|BLOCK	what happens when an address where "max-size-bytes" is specified becomes full
address-settings.address-setting.message-counter-history-day-limit	xsd:int	how many days to keep message counter history for this address	0 (days)
address-settings.address-setting.last-value-queue	xsd:boolean	whether to treat the queue as a last value queue	false
address-settings.address-setting.redistribution-delay	xsd:long	how long (in ms) to wait after the last consumer is closed on a queue before redistributing messages.	-1
address-settings.address-setting.send-to-dla-on-no-route	xsd:boolean	if there are no queues matching this address, whether to forward message to DLA (if it exists for this address)
allow-failback	xsd:boolean	Whether a server will automatically stop when a another places a request to take over its place. The use case is when a regular server stops and its backup takes over its duties, later the main server restarts and requests the server (the former backup) to stop operating.	true
async-connection-execution-enabled	xsd:boolean	Should incoming packets on the server be handed off to a thread from the thread pool for processing or should they be handled on the remoting thread?	true
bindings-directory	xsd:string	the directory to store the persisted bindings to	data/bindings
bridges	Sequence of <bridge/>	a list of bridges to create
bridges.bridge	Complex element
bridges.bridge.name (required attribute)	xsd:ID	unique name for this bridge
bridges.bridge.queue-name	xsd:IDREF	name of queue that this bridge consumes from
bridges.bridge.forwarding-address	xsd:string	address to forward to. If omitted original address is used
bridges.bridge.ha	xsd:boolean	whether this bridge supports fail-over	false
bridges.bridge.filter	Complex element
bridges.bridge.filter.string (required attribute)	xsd:string	optional core filter expression
bridges.bridge.transformer-class-name	xsd:string	optional name of transformer class
bridges.bridge.min-large-message-size	xsd:int	Any message larger than this size is considered a large message (to be sent in chunks)	102400 (bytes)
bridges.bridge.check-period	xsd:long	The period (in milliseconds) a bridge's client will check if it failed to receive a ping from the server. -1 disables this check.	30000 (ms)
bridges.bridge.connection-ttl	xsd:long	how long to keep a connection alive in the absence of any data arriving from the client. This should be greater than the ping period.	60000 (ms)
bridges.bridge.retry-interval	xsd:long	period (in ms) between successive retries	2000 (in milliseconds)
bridges.bridge.retry-interval-multiplier	xsd:double	multiplier to apply to successive retry intervals	1
bridges.bridge.max-retry-interval	xsd:long	Limit to the retry-interval growth (due to retry-interval-multiplier)	2000
bridges.bridge.reconnect-attempts	xsd:int	maximum number of retry attempts, -1 means 'no limits'	-1
bridges.bridge.use-duplicate-detection	xsd:boolean	should duplicate detection headers be inserted in forwarded messages?	true
bridges.bridge.confirmation-window-size	xsd:int	Once the bridge has received this many bytes, it sends a confirmation	(bytes, 1024 * 1024)
bridges.bridge.user	xsd:string	username, if unspecified the cluster-user is used
bridges.bridge.password	xsd:string	password, if unspecified the cluster-password is used
bridges.bridge.reconnect-attempts-same-node	xsd:int	Upon reconnection this configures the number of time the same node on the topology will be retried before reseting the server locator and using the initial connectors	10 (int, 10)
broadcast-groups	Sequence of <broadcast-group/>	a list of broadcast groups to create
broadcast-groups.broadcast-group	Complex element
broadcast-groups.broadcast-group.name (required attribute)	xsd:ID	a unique name for the broadcast group
broadcast-groups.broadcast-group.local-bind-address	xsd:string	local bind address that the datagram socket is bound to	wildcard IP address chosen by the kernel
broadcast-groups.broadcast-group.local-bind-port	xsd:int	local port to which the datagram socket is bound to	-1 (anonymous port)
broadcast-groups.broadcast-group.group-address	xsd:string	multicast address to which the data will be broadcast
broadcast-groups.broadcast-group.group-port	xsd:int	UDP port number used for broadcasting
broadcast-groups.broadcast-group.broadcast-period	xsd:long	period in milliseconds between consecutive broadcasts	2000 (in milliseconds)
broadcast-groups.broadcast-group.jgroups-file	xsd:string	Name of JGroups configuration file. If specified, the server uses JGroups for broadcasting.
broadcast-groups.broadcast-group.jgroups-channel	xsd:string	Name of JGroups Channel. If specified, the server uses the named channel for broadcasting.
broadcast-groups.broadcast-group.connector-ref	xsd:string
check-for-live-server	xsd:boolean	Whether to check the cluster for a (live) server using our own server ID when starting up. This option is only necessary for performing 'fail-back' on replicating servers. Strictly speaking this setting only applies to live servers and not to backups.	false
cluster-connections	Sequence of <cluster-connection/>	a list of cluster connections
cluster-connections.cluster-connection	Complex element
cluster-connections.cluster-connection.name (required attribute)	xsd:ID	unique name for this cluster connection
cluster-connections.cluster-connection.address	xsd:string	name of the address this cluster connection applies to
cluster-connections.cluster-connection.connector-ref	xsd:string	Name of the connector reference to use.
cluster-connections.cluster-connection.check-period	xsd:long	The period (in milliseconds) used to check if the cluster connection has failed to receive pings from another server	30000 (ms)
cluster-connections.cluster-connection.connection-ttl	xsd:long	how long to keep a connection alive in the absence of any data arriving from the client	60000 (ms)
cluster-connections.cluster-connection.min-large-message-size	xsd:int	Messages larger than this are considered large-messages	(bytes)
cluster-connections.cluster-connection.call-timeout	xsd:long	How long to wait for a reply	30000 (ms)
cluster-connections.cluster-connection.retry-interval	xsd:long	period (in ms) between successive retries	500
cluster-connections.cluster-connection.retry-interval-multiplier	xsd:double	multiplier to apply to the retry-interval	1
cluster-connections.cluster-connection.max-retry-interval	xsd:long	Maximum value for retry-interval	2000
cluster-connections.cluster-connection.reconnect-attempts	xsd:int	How many attempts should be made to reconnect after failure	-1
cluster-connections.cluster-connection.use-duplicate-detection	xsd:boolean	should duplicate detection headers be inserted in forwarded messages?	true
cluster-connections.cluster-connection.forward-when-no-consumers	xsd:boolean	should messages be load balanced if there are no matching consumers on target?	false
cluster-connections.cluster-connection.max-hops	xsd:int	maximum number of hops cluster topology is propagated	1
cluster-connections.cluster-connection.confirmation-window-size	xsd:int	The size (in bytes) of the window used for confirming data from the server connected to.	1048576
cluster-connections.cluster-connection.call-failover-timeout	xsd:long	How long to wait for a reply if in the middle of a fail-over. -1 means wait forever.	-1 (ms)
cluster-connections.cluster-connection.notification-interval	xsd:long	how often the cluster connection will notify the cluster of its existence right after joining the cluster	1000 (ms)
cluster-connections.cluster-connection.notification-attempts	xsd:int	how many times this cluster connection will notify the cluster of its existence right after joining the cluster	2
clustered	xsd:boolean	DEPRECATED. This option is deprecated and its value will be ignored (HQ221038). A HornetQ server will be "clustered" when its configuration contain a cluster-configuration.	false
cluster-password	xsd:string	Cluster password. It applies to all cluster configurations.	CHANGE ME!!
cluster-user	xsd:string	Cluster username. It applies to all cluster configurations.	HORNETQ.CLUSTER.ADMIN.USER
connection-ttl-override	xsd:long	if set, this will override how long (in ms) to keep a connection alive without receiving a ping. -1 disables this setting.	-1
connectors	Sequence of <connector/>	a list of remoting connectors configurations to create
connectors.connector	Complex element
connectors.connector.name (required attribute)	xsd:ID	Name of the connector
connectors.connector.factory-class	xsd:string	Name of the ConnectorFactory implementation
connectors.connector.param	Complex element	A key-value pair used to configure the connector. A connector can have many param's
connectors.connector.param.key (required attribute)	xsd:string	Key of a configuration parameter
connectors.connector.param.value (required attribute)	xsd:string	Value of a configuration parameter
connector-services	Sequence of <connector-service/>
connector-services.connector-service	Complex element
connector-services.connector-service.name (attribute)	xsd:string	name of the connector service
connector-services.connector-service.factory-class	xsd:string	Name of the factory class of the ConnectorService
connector-services.connector-service.param	Complex element
connector-services.connector-service.param.key (required attribute)	xsd:string	Key of a configuration parameter
connector-services.connector-service.param.value (required attribute)	xsd:string	Value of a configuration parameter
create-bindings-dir	xsd:boolean	true means that the server will create the bindings directory on start up	true
create-journal-dir	xsd:boolean	true means that the journal directory will be created	true
discovery-groups	Sequence of <discovery-group/>	a list of discovery groups to create
discovery-groups.discovery-group	Complex element
discovery-groups.discovery-group.name (required attribute)	xsd:ID	a unique name for the discovery group
discovery-groups.discovery-group.group-address	xsd:string	Multicast IP address of the group to listen on
discovery-groups.discovery-group.group-port	xsd:int	UDP port number of the multi cast group
discovery-groups.discovery-group.jgroups-file	xsd:string	Name of a JGroups configuration file. If specified, the server uses JGroups for discovery.
discovery-groups.discovery-group.jgroups-channel	xsd:string	Name of a JGroups Channel. If specified, the server uses the named channel for discovery.
discovery-groups.discovery-group.refresh-timeout	xsd:int	Period the discovery group waits after receiving the last broadcast from a particular server before removing that servers connector pair entry from its list.	10000 (in milliseconds)
discovery-groups.discovery-group.local-bind-address	xsd:string	local bind address that the datagram socket is bound to	wildcard IP address chosen by the kernel
discovery-groups.discovery-group.local-bind-port	xsd:int	local port to which the datagram socket is bound to	-1 (anonymous port)
discovery-groups.discovery-group.initial-wait-timeout	xsd:int	time to wait for an initial broadcast to give us at least one node in the cluster	10000 (milliseconds)
diverts	Sequence of <divert/>	a list of diverts to use
diverts.divert	Complex element
diverts.divert.name (required attribute)	xsd:ID	a unique name for the divert
diverts.divert.transformer-class-name	xsd:string	an optional class name of a transformer
diverts.divert.exclusive	xsd:boolean	whether this is an exclusive divert	false
diverts.divert.routing-name	xsd:string	the routing name for the divert
diverts.divert.address	xsd:string	the address this divert will divert from
diverts.divert.forwarding-address	xsd:string	the forwarding address for the divert
diverts.divert.filter	Complex element
diverts.divert.filter.string (required attribute)	xsd:string	optional core filter expression
graceful-shutdown-enabled	xsd:boolean	true means that graceful shutdown is enabled	true
graceful-shutdown-timeout	xsd:long	how long (in ms) to wait for all clients to disconnect before forcefully disconnecting the clients and proceeding with the shutdown process (-1 means no timeout)	-1
grouping-handler	Complex element	Message Group configuration
grouping-handler.name (required attribute)	xsd:string	A name identifying this grouping-handler
grouping-handler.type	LOCAL|REMOTE	Each cluster should choose 1 node to have a LOCAL grouping handler and all the other nodes should have REMOTE handlers
grouping-handler.address	xsd:string	A reference to a cluster connection address
grouping-handler.timeout	xsd:int	How long to wait for a decision	5000 (ms)
grouping-handler.group-timeout	xsd:int	How long a group binding will be used, -1 means for ever. Bindings are removed after this wait elapses. Only valid for LOCAL handlers	-1 (ms)
grouping-handler.reaper-period	xsd:long	How often the reaper will be run to check for timed out group bindings. Only valid for LOCAL handlers	30000 (ms)
id-cache-size	xsd:int	the size of the cache for pre-creating message ID's	20000
jmx-domain	xsd:string	the JMX domain used to registered HornetQ MBeans in the MBeanServer	org.hornetq
jmx-management-enabled	xsd:boolean	true means that the management API is available via JMX	true
journal-buffer-size	xsd:long	The size of the internal buffer on the journal in KiB.	501760 (490 KiB)
journal-buffer-timeout	xsd:long	The timeout (in nanoseconds) used to flush internal buffers on the journal. The exact default value depend on whether the journal is ASYNCIO or NIO.
journal-compact-min-files	xsd:int	The minimal number of data files before we can start compacting	10
journal-compact-percentage	xsd:int	The percentage of live data on which we consider compacting the journal	30
journal-directory	xsd:string	the directory to store the journal files in	data/journal
journal-file-size	xsd:int	the size (in bytes) of each journal file	10485760 (10 * 1024 * 1024 - 10 MiB)
journal-max-io	xsd:int	the maximum number of write requests that can be in the AIO queue at any one time. Default is 500 for AIO and 1 for NIO.
journal-min-files	xsd:int	how many journal files to pre-create	2
journal-sync-non-transactional	xsd:boolean	if true wait for non transaction data to be synced to the journal before returning response to client.	true
journal-sync-transactional	xsd:boolean	if true wait for transaction data to be synchronized to the journal before returning response to client	true
journal-type	ASYNCIO|NIO	the type of journal to use	ASYNCIO
large-messages-directory	xsd:string	the directory to store large messages	data/largemessages
log-delegate-factory-class-name	xsd:string	XXX
log-journal-write-rate	xsd:boolean	Whether to log messages about the journal write rate	false
management-address	xsd:string	the name of the management address to send management messages to. It is prefixed with "jms.queue" so that JMS clients can send messages to it.	jms.queue.hornetq.management
management-notification-address	xsd:string	the name of the address that consumers bind to receive management notifications	hornetq.notifications
mask-password	xsd:boolean	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	xsd:int	This 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.	2
memory-measure-interval	xsd:long	frequency to sample JVM memory in ms (or -1 to disable memory sampling)	-1 (ms)
memory-warning-threshold	xsd:int	Percentage of available memory which will trigger a warning log	25
message-counter-enabled	xsd:boolean	true means that message counters are enabled	false
message-counter-max-day-history	xsd:int	how many days to keep message counter history	10 (days)
message-counter-sample-period	xsd:long	the sample period (in ms) to use for message counters	10000
message-expiry-scan-period	xsd:long	how often (in ms) to scan for expired messages	30000
message-expiry-thread-priority	xsd:int	the priority of the thread expiring messages	3
name	xsd:string	Node name. If set, it will be used in topology notifications.
page-max-concurrent-io	xsd:int	The max number of concurrent reads allowed on paging	5
paging-directory	xsd:string	the directory to store paged messages in	data/paging
password-codec	xsd:string	Class name and its parameters for the Decoder used to decode the masked password. Ignored if mask-password is false. The format of this property is a full qualified class name optionally followed by key/value pairs.	org.hornetq.utils.DefaultSensitiveStringCodec
perf-blast-pages	xsd:int	XXX Only meant to be used by project developers	-1
persist-delivery-count-before-delivery	xsd:boolean	True means that the delivery count is persisted before delivery. False means that this only happens after a message has been cancelled.	false
persistence-enabled	xsd:boolean	true means that the server will use the file based journal for persistence.	true
persist-id-cache	xsd:boolean	true means that ID's are persisted to the journal	true
queues	Sequence of <queue/>	a list of pre configured queues to create
queues.queue	Complex element
queues.queue.name (required attribute)	xsd:ID	unique name of this queue
queues.queue.address	xsd:string	address for the queue
queues.queue.filter	Complex element
queues.queue.filter.string (required attribute)	xsd:string	optional core filter expression
queues.queue.durable	xsd:boolean	whether the queue is durable (persistent)	true
remoting-incoming-interceptors	Complex element	a list of <class-name/> elements with the names of classes to use for interceptor incoming remoting packetsunlimited sequence of <class-name/>
remoting-incoming-interceptors.class-name	xsd:string	the fully qualified name of the interceptor class
remoting-interceptors	Complex element	DEPRECATED. This option is deprecated, but it will still be honored. Any interceptor specified here will be considered an "incoming" interceptor. See <remoting-incoming-interceptors> and <remoting-outgoing-interceptors>.unlimited sequence of <class-name/>
remoting-interceptors.class-name	xsd:string	the fully qualified name of the interceptor class
remoting-outgoing-interceptors	Complex element	a list of <class-name/> elements with the names of classes to use for interceptor outcoming remoting packetsunlimited sequence of <class-name/>
remoting-outgoing-interceptors.class-name	xsd:string	the fully qualified name of the interceptor class
resolveProtocols	xsd:boolean	If true then the HornetQ Server will make use of any Protocol Managers that are in available on the classpath. If false then only the core protocol will be available, unless in Embedded mode where users can inject their own Protocol Managers.	true
run-sync-speed-test	xsd:boolean	XXX Only meant to be used by project developers	false
scheduled-thread-pool-max-size	xsd:int	Maximum number of threads to use for the scheduled thread pool	5
security-enabled	xsd:boolean	true means that security is enabled	true
security-invalidation-interval	xsd:long	how long (in ms) to wait before invalidating the security cache	10000
security-settings	Sequence of <security-setting/>	a list of security settings
security-settings.security-setting	Sequence of <permission/>
security-settings.security-setting.match (required attribute)	xsd:string	regular expression for matching security roles against addresses
security-settings.security-setting.permission	Complex element
security-settings.security-setting.permission.type (required attribute)	xsd:string	the type of permission
security-settings.security-setting.permission.roles (required attribute)	xsd:string	a comma-separated list of roles to apply the permission to
server-dump-interval	xsd:long	Interval to log server specific information (e.g. memory usage etc)	-1 (ms)
thread-pool-max-size	xsd:int	Maximum number of threads to use for the thread pool. -1 means 'no limits'.	30
transaction-timeout	xsd:long	how long (in ms) before a transaction can be removed from the resource manager after create time	300000
transaction-timeout-scan-period	xsd:long	how often (in ms) to scan for timeout transactions	1000
wild-card-routing-enabled	xsd:boolean	true means that the server supports wild card routing	true

##The jms configuration

Element Name	Element Type	Description	Default
queue	Queue	a queue to create
queue.name (attribute)	String	unique name of the queue
queue.durable	Boolean	is the queue durable?	true
queue.filter	String	optional filter expression for the queue
topic	Topic	a topic to create
topic.name (attribute)	String	unique name of the topic

Using Masked Passwords in Configuration Files

By default all passwords in ActiveMQ server's configuration files are in plain text form. This usually poses no security issues as those files should be well protected from unauthorized accessing. However, in some circumstances a user doesn't want to expose its passwords to more eyes than necessary.

ActiveMQ can be configured to use 'masked' passwords in its configuration files. A masked password is an obscure string representation of a real password. To mask a password a user will use an 'encoder'. The encoder takes in the real password and outputs the masked version. A user can then replace the real password in the configuration files with the new masked password. When ActiveMQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.

ActiveMQ provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for masking the passwords.

Password Masking in Server Configuration File

The password masking property

The server configuration file has a property that defines the default masking behaviors over the entire file scope.

mask-password: this boolean type property indicates if a password should be masked or not. Set it to "true" if you want your passwords masked. The default value is "false".

Specific masking behaviors

cluster-password

The nature of the value of cluster-password is subject to the value of property 'mask-password'. If it is true the cluster-password is masked.

Passwords in connectors and acceptors

In the server configuration, Connectors and Acceptors sometimes needs to specify passwords. For example if a users wants to use an SSL-enabled NettyAcceptor, it can specify a key-store-password and a trust-store-password. Because Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.

When a Connector or Acceptor configuration is initialised, ActiveMQ will add the "mask-password" and "password-codec" values to the Connector or Acceptors params using the keys activemq.usemaskedpassword and activemq.passwordcodec respectively. The Netty and InVM implementations will use these as needed and any other implementations will have access to these to use if they so wish.

Passwords in Core Bridge configurations

Core Bridges are configured in the server configuration file and so the masking of its 'password' properties follows the same rules as that of 'cluster-password'.

Examples

The following table summarizes the relations among the above-mentioned properties

mask-password cluster-password acceptor/connector passwords bridge password

---

absent plain text plain text plain text false plain text plain text plain text true masked masked masked

Examples

Note: In the following examples if related attributed or properties are absent, it means they are not specified in the configure file.

example 1

<cluster-password>bbc</cluster-password>

This indicates the cluster password is a plain text value ("bbc").

example 2

<mask-password>true</mask-password>
<cluster-password>80cf731af62c290</cluster-password>

This indicates the cluster password is a masked value and ActiveMQ will use its built-in decoder to decode it. All other passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.

JMS Bridge password masking

The JMS Bridges are configured and deployed as separate beans so they need separate configuration to control the password masking. A JMS Bridge has two password parameters in its constructor, SourcePassword and TargetPassword. It uses the following two optional properties to control their masking:

useMaskedPassword -- If set to "true" the passwords are masked. Default is false.

passwordCodec -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if useMaskedPassword is false. The format of this property is a full qualified class name optionally followed by key/value pairs, separated by semi-colons. For example:

<property name="useMaskedPassword">true</property> <property name="passwordCodec">com.foo.FooDecoder;key=value</property> ActiveMQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair. If passwordCodec is not specified, the built-in decoder is used.

Masking passwords in ActiveMQ ResourceAdapters and MDB activation configurations

Both ra.xml and MDB activation configuration have a 'password' property that can be masked. They are controlled by the following two optional Resource Adapter properties in ra.xml:

UseMaskedPassword -- If setting to "true" the passwords are masked. Default is false.

PasswordCodec -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if UseMaskedPassword is false. The format of this property is a full qualified class name optionally followed by key/value pairs. It is the same format as that for JMS Bridges. Example:

<config-property>
  <config-property-name>UseMaskedPassword</config-property-name>
  <config-property-type>boolean</config-property-type>
  <config-property-value>true</config-property-value>
</config-property>
<config-property>
  <config-property-name>PasswordCodec</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>com.foo.ADecoder;key=helloworld</config-property-value>
</config-property>

With this configuration, both passwords in ra.xml and all of its MDBs will have to be in masked form.

Masking passwords in activemq-users.properties

ActiveMQ's built-in security manager uses plain properties files where the user passwords are specified in plaintext forms by default. To mask those parameters the following two properties need to be set in the 'bootstrap.xml' file.

mask-password -- If set to "true" all the passwords are masked. Default is false.

password-codec -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if mask-password is false. The format of this property is a full qualified class name optionally followed by key/value pairs. It is the same format as that for JMS Bridges. Example:

<mask-password>true</mask-password>
<password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world</password-codec>

When so configured, the ActiveMQ security manager will initialize a DefaultSensitiveStringCodec with the parameters "key"->"hello world", then use it to decode all the masked passwords in this configuration file.

Choosing a decoder for password masking

As described in the previous sections, all password masking requires a decoder. A decoder uses an algorithm to convert a masked password into its original clear text form in order to be used in various security operations. The algorithm used for decoding must match that for encoding. Otherwise the decoding may not be successful.

For user's convenience ActiveMQ provides a default built-in Decoder. However a user can if they so wish implement their own.

The built-in Decoder

Whenever no decoder is specified in the configuration file, the built-in decoder is used. The class name for the built-in decoder is org.apache.activemq.utils.DefaultSensitiveStringCodec. It has both encoding and decoding capabilities. It uses java.crypto.Cipher utilities to encrypt (encode) a plaintext password and decrypt a mask string using same algorithm. Using this decoder/encoder is pretty straightforward. To get a mask for a password, just run the following in command line:

java org.apache.activemq.utils.DefaultSensitiveStringCodec "your plaintext password"

Make sure the classpath is correct. You'll get something like

Encoded password: 80cf731af62c290

Just copy "80cf731af62c290" and replace your plaintext password with it.

Using a different decoder

It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder is in ActiveMQ's classpath and configure the server to use it as follows:

<password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec>

If your decoder needs params passed to it you can do this via key/value pairs when configuring. For instance if your decoder needs say a "key-location" parameter, you can define like so:

<password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec>

Then configure your cluster-password like this:

<mask-password>true</mask-password>
<cluster-password>masked_password</cluster-password>

When ActiveMQ reads the cluster-password it will initialize the NewDecoder and use it to decode "mask_password". It also process all passwords using the new defined decoder.

Implementing your own codecs

To use a different decoder than the built-in one, you either pick one from existing libraries or you implement it yourself. All decoders must implement the org.apache.activemq.utils.SensitiveDataCodec<T> interface:

public interface SensitiveDataCodec<T>
{
   T decode(Object mask) throws Exception;

   void init(Map<String, String> params);
}

This is a generic type interface but normally for a password you just need String type. So a new decoder would be defined like

public class MyNewDecoder implements SensitiveDataCodec<String>
{
   public String decode(Object mask) throws Exception
   {
      //decode the mask into clear text password
      return "the password";
   }

   public void init(Map<String, String> params)
   {
      //initialization done here. It is called right after the decoder has been created.
   }
}

Last but not least, once you get your own decoder, please add it to the classpath. Otherwise ActiveMQ will fail to load it!