<commit_before>---
layout: mcollective
title: Getting Started
disqus: true
---
[Screencasts]: /introduction/screencasts.html
[ActiveMQ]: http://activemq.apache.org/
[EC2Demo]: /introduction/ec2demo.html
[Stomp]: http://stomp.codehaus.org/Ruby+Client
[DepRPMs]: http://www.marionette-collective.org/activemq/
[Gentoo]: /reference/os/gentoo.html
[DebianBug]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562954
[SecurityWithActiveMQ]: /reference/integration/activemq_security.html
[ActiveMQClustering]: http://www.devco.net/archives/2009/11/10/activemq_clustering.php
[ActiveMQSamples]: http://github.com/mcollective/marionette-collective/tree/master/ext/activemq/examples/
[ConfigurationReference]: /reference/basic/configuration.html
[Terminology]: /introduction/terminology.html
[SimpleRPCIntroduction]: /simplerpc/
[ControllingTheDaemon]: /reference/basic/daemon.html
[SSLSecurityPlugin]: /reference/plugins/security_ssl.html
[ConnectorStomp]: /reference/plugins/connector_stomp.html
[MessageFlowCast]: /introduction/screencasts.html#message_flow
[Plugins]: http://code.google.com/p/mcollective-plugins/

# {{page.title}}

 * TOC Placeholder
 {:toc}

Below find a rough guide to get you going, this assumes the client and server is on the same node, but servers don't need the client code installed.

For an even quicker intro to how it all works you can try our [EC2 based demo][EC2Demo]

Look at the [Screencasts] page, there are [some screencasts dealing with basic architecture, terminology and so forth][MessageFlowCast] that you might find helpful before getting started.

## Requirements
We try to keep the requirements on external Gems to a minimum, you only need:

 * A Stomp server, tested against [ActiveMQ]
 * Ruby
 * Rubygems
 * [Ruby Stomp Client][Stomp]

RPMs for these are available [here][DepRPMs].

Information on installing mcollective and stomp from within Gentoo's portage are available [here][Gentoo].

**NOTE: You need version Stomp Gem 1.1 for mcollective up to 0.4.5.  mcollective 0.4.6 onward supports 1.1 and 1.1.6 and newer**


## ActiveMQ
I've developed this against ActiveMQ.  It should work against other Stomp servers but I suspect if you choose 
one without username and password support you might have problems, please let me know if that's the case 
and I'll refactor the code around that.

Full details on setting up and configuring ActiveMQ is out of scope for this, but you can follow these simple 
setup instructions for initial testing (make sure JDK is installed, see below for Debian specific issue regarding JDK):

### Download and Install
 1. Download the ActiveMQ "binary" package (for Unix) from [ActiveMQ]
 1. Extract the contents of the archive:
 1. cd into the activemq directory
 1. Execute the activemq binary 

{% highlight console %}
   % tar xvzf activemq-x.x.x.tar.gz
   % cd activemq-x.x.x
   % bin/activemq
{% endhighlight %}

Below should help you get stomp and a user going. For their excellent full docs please see [ActiveMQ].  
There are also tested configurations in [the ext directory][ActiveMQSamples]

A spec file can be found in the *ext* directory on GitHub that can be used to build RPMs for RedHat/CentOS/Fedora 
you need *tanukiwrapper* which you can find from *jpackage*, it runs fine under OpenJDK that comes with recent 
versions of these Operating Systems.  I've uploaded some RPMs and SRPMs [here][DepRPMs].

For Debian systems you'd be better off using OpenJDK than Sun JDK, there's a known issue [#562954][DebianBug].

### Configuring Stomp
First you should configure ActiveMQ to listen on the Stomp protocol

And then you should add a user or two, to keep it simple we'll just add one user, the template file will hopefully make it obvious where this goes, it should be in the _broker_ block:

*Note: This config is for ActiveMQ 5.3*

{% highlight xml %}
<beans
  xmlns="http://www.springframework.org/schema/beans"
  xmlns:amq="http://activemq.apache.org/schema/core"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
  http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd   
  http://activemq.apache.org/camel/schema/spring http://activemq.apache.org/camel/schema/spring/camel-spring.xsd">

   <broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" useJmx="true">
    <transportConnectors>
       <transportConnector name="openwire" uri="tcp://0.0.0.0:6166"/>
       <transportConnector name="stomp"   uri="stomp://0.0.0.0:6163"/>
    </transportConnectors>

    <plugins>
      <simpleAuthenticationPlugin>
        <users>
          <authenticationUser username="mcollective" password="<PASSWORD>" groups="systemusers,everyone"/>
        </users>
      </simpleAuthenticationPlugin>

      <authorizationPlugin>
        <map>
          <authorizationMap>
            <authorizationEntries>
              <authorizationEntry topic="mcollective.>" write="systemusers" read="systemusers" admin="systemusers" />
              <authorizationEntry topic="ActiveMQ.Advisory.>" read="everyone,all" write="everyone,all" admin="everyone,all"/>
            </authorizationEntries>
          </authorizationMap>
        </map>
      </authorizationPlugin>
    </plugins>
   </broker>
</beans>
{% endhighlight %}
<commit_msg>Issue 121 - Update activemq examples in docs and in ext for 5.4<commit_after>---
layout: mcollective
title: Getting Started
disqus: true
---
[Screencasts]: /introduction/screencasts.html
[ActiveMQ]: http://activemq.apache.org/
[EC2Demo]: /introduction/ec2demo.html
[Stomp]: http://stomp.codehaus.org/Ruby+Client
[DepRPMs]: http://www.marionette-collective.org/activemq/
[Gentoo]: /reference/os/gentoo.html
[DebianBug]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562954
[SecurityWithActiveMQ]: /reference/integration/activemq_security.html
[ActiveMQClustering]: http://www.devco.net/archives/2009/11/10/activemq_clustering.php
[ActiveMQSamples]: http://github.com/mcollective/marionette-collective/tree/master/ext/activemq/examples/
[ConfigurationReference]: /reference/basic/configuration.html
[Terminology]: /introduction/terminology.html
[SimpleRPCIntroduction]: /simplerpc/
[ControllingTheDaemon]: /reference/basic/daemon.html
[SSLSecurityPlugin]: /reference/plugins/security_ssl.html
[ConnectorStomp]: /reference/plugins/connector_stomp.html
[MessageFlowCast]: /introduction/screencasts.html#message_flow
[Plugins]: http://code.google.com/p/mcollective-plugins/

# {{page.title}}

 * TOC Placeholder
 {:toc}

Below find a rough guide to get you going, this assumes the client and server is on the same node, but servers don't need the client code installed.

For an even quicker intro to how it all works you can try our [EC2 based demo][EC2Demo]

Look at the [Screencasts] page, there are [some screencasts dealing with basic architecture, terminology and so forth][MessageFlowCast] that you might find helpful before getting started.

## Requirements
We try to keep the requirements on external Gems to a minimum, you only need:

 * A Stomp server, tested against [ActiveMQ]
 * Ruby
 * Rubygems
 * [Ruby Stomp Client][Stomp]

RPMs for these are available [here][DepRPMs].

Information on installing mcollective and stomp from within Gentoo's portage are available [here][Gentoo].

**NOTE: You need version Stomp Gem 1.1 for mcollective up to 0.4.5.  mcollective 0.4.6 onward supports 1.1 and 1.1.6 and newer**


## ActiveMQ
I've developed this against ActiveMQ.  It should work against other Stomp servers but I suspect if you choose 
one without username and password support you might have problems, please let me know if that's the case 
and I'll refactor the code around that.

Full details on setting up and configuring ActiveMQ is out of scope for this, but you can follow these simple 
setup instructions for initial testing (make sure JDK is installed, see below for Debian specific issue regarding JDK):

### Download and Install
 1. Download the ActiveMQ "binary" package (for Unix) from [ActiveMQ]
 1. Extract the contents of the archive:
 1. cd into the activemq directory
 1. Execute the activemq binary 

{% highlight console %}
   % tar xvzf activemq-x.x.x.tar.gz
   % cd activemq-x.x.x
   % bin/activemq
{% endhighlight %}

Below should help you get stomp and a user going. For their excellent full docs please see [ActiveMQ].  
There are also tested configurations in [the ext directory][ActiveMQSamples]

A spec file can be found in the *ext* directory on GitHub that can be used to build RPMs for RedHat/CentOS/Fedora 
you need *tanukiwrapper* which you can find from *jpackage*, it runs fine under OpenJDK that comes with recent 
versions of these Operating Systems.  I've uploaded some RPMs and SRPMs [here][DepRPMs].

For Debian systems you'd be better off using OpenJDK than Sun JDK, there's a known issue [#562954][DebianBug].

### Configuring Stomp
First you should configure ActiveMQ to listen on the Stomp protocol

And then you should add a user or two, to keep it simple we'll just add one user, the template file will hopefully make it obvious where this goes, it should be in the _broker_ block:

*Note: This config is for ActiveMQ 5.3*

{% highlight xml %}
<beans
  xmlns="http://www.springframework.org/schema/beans"
  xmlns:amq="http://activemq.apache.org/schema/core"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
  http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd   
  http://activemq.apache.org/camel/schema/spring http://activemq.apache.org/camel/schema/spring/camel-spring.xsd">

   <broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" useJmx="true">
    <plugins>
      <simpleAuthenticationPlugin>
        <users>
          <authenticationUser username="mcollective" password="<PASSWORD>" groups="systemusers,everyone"/>
        </users>
      </simpleAuthenticationPlugin>

      <authorizationPlugin>
        <map>
          <authorizationMap>
            <authorizationEntries>
              <authorizationEntry topic="mcollective.>" write="systemusers" read="systemusers" admin="systemusers" />
              <authorizationEntry topic="ActiveMQ.Advisory.>" read="everyone,all" write="everyone,all" admin="everyone,all"/>
            </authorizationEntries>
          </authorizationMap>
        </map>
      </authorizationPlugin>
    </plugins>

    <transportConnectors>
       <transportConnector name="openwire" uri="tcp://0.0.0.0:6166"/>
       <transportConnector name="stomp"   uri="stomp://0.0.0.0:6163"/>
    </transportConnectors>
   </broker>
</beans>
{% endhighlight %}

{'fraction_non_alphanumeric': 0.10705730606228119, 'fraction_numerical': 0.012622074811129537, 'mean_word_length': 4.2822384428223845, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 59, 'https://': 0, 'lorem ipsum': 0, 'www.': 12, 'xml': 10}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7546245', 'n_tokens_mistral': 3430, 'n_tokens_neox': 3173, 'n_words': 1037}