5 [Screencasts]: /mcollective/screencasts.html
6 [ActiveMQ]: http://activemq.apache.org/
7 [EC2Demo]: /mcollective/ec2demo.html
8 [Stomp]: http://stomp.codehaus.org/Ruby+Client
9 [DepRPMs]: http://www.marionette-collective.org/activemq/
10 [DebianBug]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562954
11 [SecurityWithActiveMQ]: /mcollective/reference/integration/activemq_security.html
12 [ActiveMQClustering]: http://www.devco.net/archives/2009/11/10/activemq_clustering.php
13 [ActiveMQSamples]: http://github.com/puppetlabs/marionette-collective/tree/master/ext/activemq/examples/
14 [ConfigurationReference]: /mcollective/reference/basic/configuration.html
15 [Terminology]: /mcollective/terminology.html
16 [SimpleRPCIntroduction]: /mcollective/simplerpc/
17 [ControllingTheDaemon]: /mcollective/reference/basic/daemon.html
18 [SSLSecurityPlugin]: /mcollective/reference/plugins/security_ssl.html
19 [AESSecurityPlugin]: /mcollective/reference/plugins/security_aes.html
20 [ConnectorStomp]: /mcollective/reference/plugins/connector_stomp.html
21 [MessageFlowCast]: /mcollective/screencasts.html#message_flow
22 [Plugins]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
23 [RedHatGuide]: gettingstarted_redhat.html
24 [DebianGuide]: gettingstarted_debian.html
26 *NOTE:* We are currently improving the Getting Started documentation. Red Hat and CentOS users can refer to [our Redhat guide][RedHatGuide]. Debian users can refer to [our Debian guide][DebianGuide].
28 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.
30 For an even quicker intro to how it all works you can try our [EC2 based demo][EC2Demo]
32 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.
35 We try to keep the requirements on external Gems to a minimum, you only need:
37 * A Stomp server, tested against [ActiveMQ]
40 * [Ruby Stomp Client][Stomp]
42 RPMs for these are available [here][DepRPMs].
45 I've developed this against ActiveMQ. It should work against other Stomp servers but I suspect if you choose
46 one without username and password support you might have problems, please let me know if that's the case
47 and I'll refactor the code around that.
49 Full details on setting up and configuring ActiveMQ is out of scope for this, but you can follow these simple
50 setup instructions for initial testing (make sure JDK is installed, see below for Debian specific issue regarding JDK):
52 ### Download and Install
53 1. Download the ActiveMQ "binary" package (for Unix) from [ActiveMQ]
54 1. Extract the contents of the archive:
55 1. cd into the activemq directory
56 1. Execute the activemq binary
58 {% highlight console %}
59 % tar xvzf activemq-x.x.x.tar.gz
64 Below should help you get stomp and a user going. For their excellent full docs please see [ActiveMQ].
65 There are also tested configurations in [the ext directory][ActiveMQSamples]
67 A spec file can be found in the *ext* directory on GitHub that can be used to build RPMs for RedHat/CentOS/Fedora
68 you need *tanukiwrapper* which you can find from *jpackage*, it runs fine under OpenJDK that comes with recent
69 versions of these Operating Systems. I've uploaded some RPMs and SRPMs [here][DepRPMs].
71 For Debian systems you'd be better off using OpenJDK than Sun JDK, there's a known issue [#562954][DebianBug].
74 First you should configure ActiveMQ to listen on the Stomp protocol
76 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:
78 *Note: This config is for ActiveMQ 5.4*
82 xmlns="http://www.springframework.org/schema/beans"
83 xmlns:amq="http://activemq.apache.org/schema/core"
84 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
85 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
86 http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd
87 http://activemq.apache.org/camel/schema/spring http://activemq.apache.org/camel/schema/spring/camel-spring.xsd">
89 <broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" useJmx="true">
91 <managementContext createConnector="false"/>
95 <statisticsBrokerPlugin/>
96 <simpleAuthenticationPlugin>
98 <authenticationUser username="mcollective" password="marionette" groups="mcollective,everyone"/>
99 <authenticationUser username="admin" password="secret" groups="mcollective,admin,everyone"/>
101 </simpleAuthenticationPlugin>
102 <authorizationPlugin>
105 <authorizationEntries>
106 <authorizationEntry queue=">" write="admins" read="admins" admin="admins" />
107 <authorizationEntry topic=">" write="admins" read="admins" admin="admins" />
108 <authorizationEntry topic="mcollective.>" write="mcollective" read="mcollective" admin="mcollective" />
109 <authorizationEntry queue="mcollective.>" write="mcollective" read="mcollective" admin="mcollective" />
110 <authorizationEntry topic="ActiveMQ.Advisory.>" read="everyone" write="everyone" admin="everyone"/>
111 </authorizationEntries>
114 </authorizationPlugin>
120 <memoryUsage limit="20 mb"/>
123 <storeUsage limit="1 gb" name="foo"/>
126 <tempUsage limit="100 mb"/>
131 <transportConnectors>
132 <transportConnector name="openwire" uri="tcp://0.0.0.0:6166"/>
133 <transportConnector name="stomp" uri="stomp://0.0.0.0:6163"/>
134 </transportConnectors>
139 This creates a user *mcollective* with the password *marionette* and give it access to read/write/admin */topic/mcollective.`*`*.
141 Save the above code as activemq.xml and run activemq as - if installing from a package probably _/etc/activemq/activemq.xml_:
143 Else your package would have a RC script:
145 {% highlight console %}
146 # /etc/init.d/activemq start
149 For further info about ActiveMQ settings you might need see [SecurityWithActiveMQ] and [ActiveMQClustering].
151 There are also a few known to work and tested [configs in git][ActiveMQSamples].
155 ### Download and Extract
156 Grab a copy of the mcollective ideally you'd use a package for your distribution else there's a tarfile that
157 you can use, you can extract it wherever you want, the RPMs or deps will put files in Operating System compatible
158 locations. If you use the tarball you'll need to double check all the paths in the config files below.
161 You'll need to tweak some configs in */etc/mcollective/client.cfg*, a full reference of config settings can be
162 found [here][ConfigurationReference]:
164 Mostly what you'll need to change is the *identity*, *plugin.stomp.`*`* and the *plugin.psk*:
168 libdir = /usr/libexec/mcollective
173 # connector plugin config
175 plugin.stomp.host = stomp.your.net
176 plugin.stomp.port = 6163
177 plugin.stomp.user = unset
178 plugin.stomp.password = unset
180 # security plugin config
181 securityprovider = psk
182 plugin.psk = abcdefghj
185 You should also create _/etc/mcollective/server.cfg_ here's a sample, , a full reference of config settings can be found here [ConfigurationReference]:
189 libdir = /usr/libexec/mcollective
190 logfile = /var/log/mcollective.log
196 registerinterval = 300
198 # connector plugin config
200 plugin.stomp.host = stomp.your.net
201 plugin.stomp.port = 6163
202 plugin.stomp.user = mcollective
203 plugin.stomp.password = password
207 plugin.yaml = /etc/mcollective/facts.yaml
209 # security plugin config
210 securityprovider = psk
211 plugin.psk = abcdefghj
214 Replace the *plugin.stomp.host* with your server running ActiveMQ and replace the *plugin.psk* with a Pre-Shared Key of your own.
216 The STOMP connector supports other options like failover pools, see [ConnectorStomp] for full details.
219 By default - and for this setup - we'll use a simple YAML file for a fact source, later on you can use Reductive Labs Facter or something else.
221 Create */etc/mcollective/facts.yaml* along these lines:
230 If you installed from a package start it with the RC script, else look in the source you'll find a LSB compatible RC script to start it.
232 ### Test from a client
233 If all is setup you can test with the client code:
235 {% highlight console %}
237 your.domain.com time=74.41 ms
239 ---- ping statistics ----
240 1 replies max: 74.41 min: 74.41 avg: 74.41
243 This sent a simple 'hello' packet out to the network and if you started up several of the *mcollectived.rb* processes on several machines you
244 would have seen several replies, be sure to give each a unique *identity* in the config.
246 At this point you can start exploring the discovery features for example:
248 {% highlight console %}
249 % mco find --with-fact country=uk
253 This searches all systems currently active for ones with a fact *country=uk*, it got the data from the yaml file you made earlier.
255 If you use confiuration management tools like puppet and the nodes are setup with classes with *classes.txt* in */var/lib/puppet* then you
256 can search for nodes with a specific class on them - the locations will configurable soon:
258 {% highlight console %}
259 % mco find --with-class common::linux
263 Chef does not yet support such a list natively but we have some details on the wiki to achieve the same with Chef.
265 The filter commands are important they will be the main tool you use to target only parts of your infrastructure with calls to agents.
267 See the *--help* option to the various *mco `*`* commands for available options. You can now look at some of the available plugins and
268 play around, you might need to run the server process as root if you want to play with services etc.
271 We provide limited default plugins, you can look on our sister project [MCollective Plugins][Plugins] where you will
272 find various plugins to manage packages, services etc.
275 From here you should look at the rest of the wiki pages some key pages are:
277 * [Screencasts] - Get a hands-on look at what is possible
279 * [Introduction to Simple RPC][SimpleRPCIntroduction] - a simple to use framework for writing clients and agents
280 * [ControllingTheDaemon] - Controlling a running daemon
281 * [AESSecurityPlugin] - Using AES+RSA for secure message encryption and authentication of clients
282 * [SSLSecurityPlugin] - Using SSL for secure message signing and authentication of clients
283 * [ConnectorStomp] - Full details on the Stomp adapter including failover pools