website/reference/plugins/connector_activemq.md

   1 ---
   2 layout: default
   3 title: ActiveMQ Connector
   4 toc: false
   5 ---
   6
   7 [STOMP]: http://stomp.codehaus.org/
   8 [wildcard]: http://activemq.apache.org/wildcards.html
   9 [subcollectives]: /reference/basic/subcollectives.html
  10 [activemq_config]: /mcollective/deploy/middleware/activemq.html
  11
  12
  13 The ActiveMQ connector uses the [STOMP][] rubygem to connect to ActiveMQ servers.  It is specifically optimized for ActiveMQ
  14 and uses features in ActiveMQ 5.5.0 and later.
  15
  16 This plugin requires version _1.2.2_ or newer of the Stomp gem.
  17
  18 ## Differences between ActiveMQ connector and Stomp Connector
  19
  20 ### Topic and Queue Names
  21
  22 The new connector uses different destination names from the old stomp connector.
  23
  24 MCollective uses the following destination names. This list uses standard [ActiveMQ destination wildcards][wildcard]. "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.
  25
  26 Topics:
  27
  28 - `ActiveMQ.Advisory.>` (built-in topics that all ActiveMQ producers and consumers need all permissions on)
  29 - `COLLECTIVE.*.agent` (for each agent plugin, where the `*` is the name of the plugin)
  30
  31 Queues:
  32
  33 - `COLLECTIVE.nodes` (used for direct addressing; this is a single destination that uses JMS selectors, rather than a group of destinations)
  34 - `COLLECTIVE.reply.>` (where the continued portion is a request ID)
  35
  36 Note especially that:
  37
  38 * We can now do direct addressing to specific nodes.
  39 * Replies now go directly to the instigating client instead of being brodcast on a topic.
  40
  41 This has big impact on overall CPU usage by clients on busy networks, and also optimizes the traffic flow on
  42 networks with many brokers.
  43
  44
  45 ## Configuring ActiveMQ
  46
  47 See [the ActiveMQ config reference][activemq_config] 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.
  48
  49
  50 ## Configuring MCollective
  51
  52 MCollective clients and servers use the same connector settings, although the value of settings involving credentials will vary.
  53
  54 ### Failover Pools
  55
  56 A sample configuration can be seen below.  Note this plugin does not support the old style config of the Stomp connector.
  57
  58 {% highlight ini %}
  59 connector = activemq
  60 plugin.activemq.pool.size = 2
  61 plugin.activemq.pool.1.host = stomp1
  62 plugin.activemq.pool.1.port = 61613
  63 plugin.activemq.pool.1.user = me
  64 plugin.activemq.pool.1.password = secret
  65
  66 plugin.activemq.pool.2.host = stomp2
  67 plugin.activemq.pool.2.port = 61613
  68 plugin.activemq.pool.2.user = me
  69 plugin.activemq.pool.2.password = secret
  70 {% endhighlight %}
  71
  72 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
  73 with the environment variables `STOMP_USER`, `STOMP_PASSWORD`.
  74
  75 If you do not specify a port it will default to _61613_
  76
  77 You can also specify the following options for the Stomp gem, these are the defaults in the Stomp gem: <!-- last checked: v. 1.1.6 of the gem -->
  78
  79 {% highlight ini %}
  80 plugin.activemq.initial_reconnect_delay = 0.01
  81 plugin.activemq.max_reconnect_delay = 30.0
  82 plugin.activemq.use_exponential_back_off = true
  83 plugin.activemq.back_off_multiplier = 2
  84 plugin.activemq.max_reconnect_attempts = 0
  85 plugin.activemq.randomize = false
  86 plugin.activemq.timeout = -1
  87 {% endhighlight %}
  88
  89 ### Message Priority
  90
  91 ActiveMQ messages support priorities, you can pass in the needed priority header by setting:
  92
  93 {% highlight ini %}
  94 plugin.activemq.priority = 4
  95 {% endhighlight %}