The ActiveMQ connector uses the STOMP rubygem to connect to ActiveMQ servers. It is specifically optimized for ActiveMQ and uses features in ActiveMQ 5.5.0 and later.
This plugin requires version 1.2.2 or newer of the Stomp gem.
The new connector uses different destination names from the old stomp connector.
MCollective uses the following destination names. This list uses standard ActiveMQ destination wildcards. “COLLECTIVE” is the name of the collective being used; by default, this is
mcollective, but if you are using subcollectives, each one is implemented as an equal peer of the default collective.
ActiveMQ.Advisory.>(built-in topics that all ActiveMQ producers and consumers need all permissions on)
COLLECTIVE.*.agent(for each agent plugin, where the
*is the name of the plugin)
COLLECTIVE.nodes(used for direct addressing; this is a single destination that uses JMS selectors, rather than a group of destinations)
COLLECTIVE.reply.>(where the continued portion is a request ID)
Note especially that:
This has big impact on overall CPU usage by clients on busy networks, and also optimizes the traffic flow on networks with many brokers.
See the ActiveMQ config reference for details on configuring ActiveMQ for this connector. As recommended at the top of the reference, you should skim the sections you care about and edit an example config file while reading.
MCollective clients and servers use the same connector settings, although the value of settings involving credentials will vary.
A sample configuration can be seen below. Note this plugin does not support the old style config of the Stomp connector.
This gives it 2 servers to attempt to connect to, if the first one fails it will use the second. Usernames and passwords can be set
with the environment variables
If you do not specify a port it will default to 61613
You can also specify the following options for the Stomp gem, these are the defaults in the Stomp gem:
ActiveMQ messages support priorities, you can pass in the needed priority header by setting:
A common problem is that idle STOMP connections get expired by session tracking firewalls and NAT devices. Version 1.1 of the STOMP protocol combats this with protocol level heartbeats, which can be configured with these settings:
This feature is avaiable from version 2.4.0 and requires version 1.2.10 or newer of the stomp gem.
More information about STOMP heartbeats can be found in the STOMP specification
Specify the timeout for the TCP+SSL connection to the middleware.
Whether to use exponential backoff when reconnecting to the middleware.
use_exponential_back_off is set, the initial delay to use when
reconnecting to the middleware.
use_exponential_back_off is set, the maximum delay to use when
reconnecting to the middleware.
use_exponential_back_off is set, the amount to increase the
delay by (up to
The number of times to attempt to connect to the middleware. 0 means no limit (retry forever).
Setting this value enables STOMP 1.1 heartbeats, and sets the interval to send/receive heartbeat messages to that number of seconds.
heartbeat_interval is set it will request STOMP 1.1 but support fallback
to 1.0. You can force STOMP 1.1 only operation by setting this to false.
Maximum amount of heartbeat read failures to allow before assuming the connection is dead and reconnecting.
Maximum amount of heartbeat lock obtain failures before assuming the connection is dead and reconnecting. This setting is best left at 0 due to MCollective’s usage patterns.
Specifies the priority of the messages sent to ActiveMQ. 1 is the lowest priority, 9 is the highest, and unspecified is the same as the default value (4).
Whether to randomize the order of the connection pool before connecting.
Specifies the size of the connector pool.
The hostname of this middleware server.
The port number to connect to for this middleware server.
The username to connect with to this middleware server. If the
STOMP_USER environment variable is set this value will be used
The password to connect with to this middleware server. If the
STOMP_PASSWORD environment variable is set this value will be used
Whether to use TLS when connecting to this middleware server.
Whether to allow unverified TLS if the ca/cert/key settings aren’t set.
The CA certificate to use when verifying the middlewares
certificate. Must be the fully-qualified path to a
The certificate to present when connecting to the middleware. Must be
the fully-qualified path to a
.pem file. MCollective will also
check the environment variable
for the client’s ssl cert.
The private key corresponding to this node’s certificate. Must be the
fully-qualified path to a
.pem file. MCollective will also check
the environment variable
MCOLLECTIVE_ACTIVEMQ_POOL1_SSL_KEY for the
client’s ssl key.
The SSL ciphers to use when communicating with this middleware server.
Whether to use a single target for all agents in a node. This is an optimization that may make sense when running collectives with several thousands of nodes in order to reduce the number of subscriptions in the message broker. This is a trade-off between increasing network traffic by delivering messages to all nodes - and letting them select messages they care about - versus increasing work in the message broker to handle large numbers of subscriptions.