website/reference/plugins/connector_activemq.md

   1 ---
   2 layout: default
   3 title: ActiveMQ Connector
   4 toc: false
   5 ---
   6 [STOMP]: http://stomp.codehaus.org/
   7
   8 The ActiveMQ connector uses the [STOMP] rubygem to connect to ActiveMQ servers.  It is specifically optimiszed for ActiveMQ
   9 and uses features in ActiveMQ 5.5.0 and later.
  10
  11 This code will only work with version _1.1.8_ or newer of the Stomp gem.
  12
  13 ## Differences between ActiveMQ connector and Stomp Connector
  14
  15 The ActiveMQ connector requires MCollective 2.0.0 or newer and introduce a new structure to the middleware messsages.
  16
  17  * Replies goes direct to clients using short lived queues
  18  * Agent topics are called */topic/&lt;collective&gt;.&lt;agent_name&gt;.agent*
  19  * Support for point to point messages are added by using _/queue/&lt;collective&gt;.nodes_ and using JMS selectors.
  20
  21 The use of short lived queues mean that replies are now going to go back only to the person who sent the request.
  22 This has big impact on overall CPU usage by clients on busy networks but also optimize the traffic flow on
  23 networks with many brokers.
  24
  25 Point to Point messages means each node has a unique subscription, the approach using JMS Selectors means
  26 internally to ActiveMQ only a single thread will be dedicated to this rather than 1 per connected node.
  27
  28 Before using this plugin you will need to make appropriate adjustments to your ActiveMQ Access Control Lists.
  29
  30 ## Configuring ActiveMQ
  31 For best behavior there are a few settings you need in your _activemq.xml_
  32
  33 ### Remove unused queues
  34 We use uniquely named queues for replies.  As queues will live forever we need to get ActiveMQ to remove
  35 queues we are done with else they will just add up and grow forever.
  36
  37 {% highlight xml %}
  38 <destinationPolicy>
  39   <policyMap>
  40     <policyEntries>
  41       <policyEntry queue="*.reply.>" gcInactiveDestinations="true" inactiveTimoutBeforeGC="300000" />
  42     </policyEntries>
  43   </policyMap>
  44 </destinationPolicy>
  45 {% endhighlight %}
  46
  47 The above policy will instruct ActiveMQ to remove dead queues after 5 minutes.
  48
  49 ### Optimize network usage for direct requests in a network of brokers
  50 If you are using a network of brokers you will need to make a big change to how that works.
  51 At present we tend to have 1 bi-directional connection for everything, with direct requests
  52 we dedicate a bi-directional connection for these queues leaving the other just for topics.
  53
  54 {% highlight xml %}
  55 <networkConnectors>
  56   <networkConnector
  57         name="stomp1-stomp2-topics"
  58         uri="static:(tcp://stomp2.xx.net:6166)"
  59         userName="amq"
  60         password="secret"
  61         duplex="true"
  62         decreaseNetworkConsumerPriority="true"
  63         networkTTL="2"
  64         dynamicOnly="true">
  65         <excludedDestinations>
  66                 <queue physicalName=">" />
  67         </excludedDestinations>
  68   </networkConnector>
  69   <networkConnector
  70         name="stomp1-stomp2-queues"
  71         uri="static:(tcp://stomp2.xx.net:6166)"
  72         userName="amq"
  73         password="secret"
  74         duplex="true"
  75         decreaseNetworkConsumerPriority="true"
  76         networkTTL="2"
  77         dynamicOnly="true"
  78         conduitSubscriptions="false">
  79         <excludedDestinations>
  80                 <topic physicalName=">" />
  81         </excludedDestinations>
  82   </networkConnector>
  83 </networkConnectors>
  84 {% endhighlight %}
  85
  86 You will need to adjust the TTL for your network.  Note the queue connection has a different
  87 _conduitSubscriptions_ policy than the topic one, you have to create these different connections
  88 and set this policy for everything to work correctly.
  89
  90 ## Configuring MCollective
  91
  92 ### Common Options
  93 The most basic configuration method is supported in all versions of the gem:
  94
  95 ### Failover Pools
  96 A sample configuration can be seen below.  Note this plugin does not support the old style config of the Stomp connector.
  97
  98 {% highlight ini %}
  99 connector = activemq
 100 plugin.activemq.pool.size = 2
 101 plugin.activemq.pool.1.host = stomp1
 102 plugin.activemq.pool.1.port = 6163
 103 plugin.activemq.pool.1.user = me
 104 plugin.activemq.pool.1.password = secret
 105
 106 plugin.activemq.pool.2.host = stomp2
 107 plugin.activemq.pool.2.port = 6163
 108 plugin.activemq.pool.2.user = me
 109 plugin.activemq.pool.2.password = secret
 110 {% endhighlight %}
 111
 112 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
 113 with the environment variables STOMP_USER, STOMP_PASSWORD.
 114
 115 If you do not specify a port it will default to _61613_
 116
 117 You can also specify the following options for the Stomp gem, these are the defaults in the Stomp 1.1.6 gem:
 118
 119 {% highlight ini %}
 120 plugin.activemq.initial_reconnect_delay = 0.01
 121 plugin.activemq.max_reconnect_delay = 30.0
 122 plugin.activemq.use_exponential_back_off = true
 123 plugin.activemq.back_off_multiplier = 2
 124 plugin.activemq.max_reconnect_attempts = 0
 125 plugin.activemq.randomize = false
 126 plugin.activemq.timeout = -1
 127 {% endhighlight %}
 128
 129 ### Message Priority
 130
 131 ActiveMQ messages support priorities, you can pass in the needed priority header by setting:
 132
 133 {% highlight ini %}
 134 plugin.activemq.priority = 4
 135 {% endhighlight %}