website/reference/plugins/connector_stomp.md

   1 ---
   2 layout: default
   3 title: STOMP Connector
   4 toc: false
   5 ---
   6 [STOMP]: http://stomp.codehaus.org/
   7
   8 The stomp connector uses the [STOMP] rubygem to connect to compatible servers.  This is known to work with ActiveMQ and Stompserver.  Anecdotal evidence suggests it works with RabbitMQ's Stomp plugin.
   9
  10 This code will only work with version _1.1_ and _1.1.6_ or newer of the Stomp gem, the in between versions have threading issues.
  11
  12 As this connector tries to be as generic as possible it is hard to support all the advanced features of MCollective using it.  We do not recommend you use the directed mode
  13 using this plugin, instead look towards specific ones written for ActiveMQ or your chosen middleware.
  14
  15 ## Middleware Layout
  16
  17 For broadcast messages this connector will create _topics_ with names like _/topic/&lt;collective&gt;.&lt;agent&gt;.command_ and replies will go to
  18 _/topic/&lt;collective&gt;.&lt;agent&gt;.reply_
  19
  20 For directed messages it will create queues with names like _/queue/&lt;collective&gt;.mcollective.&lt;md5 hash of identity&gt;_.
  21
  22 You should configure appropriate ACLs on your middleware to allow this scheme
  23
  24 ## Configuring
  25
  26 ### Common Options
  27 The most basic configuration method is supported in all versions of the gem:
  28
  29 {% highlight ini %}
  30 connector = stomp
  31 plugin.stomp.base64 = false
  32 plugin.stomp.host = stomp.my.net
  33 plugin.stomp.port = 6163
  34 plugin.stomp.user = me
  35 plugin.stomp.password = secret
  36 {% endhighlight %}
  37
  38 You can override all of these settings using environment variables STOMP_SERVER, STOMP_PORT, STOMP_USER, STOMP_PASSWORD.  It is recommended that your _client.cfg_ do not have usernames and passwords in it, users should set their own in the environment.
  39
  40 If you are seeing issues with the Stomp gem logging protocol errors and resetting your connections, especially if you are using Ruby on Rails then set the _plugin.stomp.base64_ to true, this adds an additional layer of encoding on packets to make sure they don't interfere with UTF8 encoding used in Rails.
  41
  42 ### Failover Pools
  43 Newer versions of the Stomp gem supports failover between multiple Stomp servers, you need at least _1.1.6_ to use this.
  44
  45 If you are using version _1.1.9_ and newer of the Stomp Gem and this method of configuration you will also receive more detailed
  46 logging about connections, failures and other significant events.
  47
  48 {% highlight ini %}
  49 connector = stomp
  50 plugin.stomp.pool.size = 2
  51 plugin.stomp.pool.host1 = stomp1
  52 plugin.stomp.pool.port1 = 6163
  53 plugin.stomp.pool.user1 = me
  54 plugin.stomp.pool.password1 = secret
  55
  56 plugin.stomp.pool.host2 = stomp2
  57 plugin.stomp.pool.port2 = 6163
  58 plugin.stomp.pool.user2 = me
  59 plugin.stomp.pool.password2 = secret
  60 {% endhighlight %}
  61
  62 This gives it 2 servers to attempt to connect to, if the first one fails it will use the second.  As before usernames and passwords can be set with STOMP_USER, STOMP_PASSWORD.
  63
  64 If you do not specify a port it will default to _6163_
  65
  66 When using pools you can also specify the following options, these are the defaults in the Stomp 1.1.6 gem:
  67
  68 {% highlight ini %}
  69 plugin.stomp.pool.initial_reconnect_delay = 0.01
  70 plugin.stomp.pool.max_reconnect_delay = 30.0
  71 plugin.stomp.pool.use_exponential_back_off = true
  72 plugin.stomp.pool.back_off_multiplier = 2
  73 plugin.stomp.pool.max_reconnect_attempts = 0
  74 plugin.stomp.pool.randomize = false
  75 plugin.stomp.pool.timeout = -1
  76 plugin.stomp.pool.connect_timeout = 30
  77 {% endhighlight %}
  78
  79 ### Message Priority
  80
  81 As of version 5.4 of ActiveMQ messages support priorities, you can pass in the needed
  82 priority header by setting:
  83
  84 {% highlight ini %}
  85 plugin.stomp.priority = 4
  86 {% endhighlight %}