5 [Screencasts]: /mcollective/screencasts.html
6 [ActiveMQ]: http://activemq.apache.org/
7 [RabbitMQ]: http://www.rabbitmq.com/
8 [EC2Demo]: /mcollective/ec2demo.html
9 [Stomp]: http://stomp.codehaus.org/Ruby+Client
10 [DepRPMs]: http://www.marionette-collective.org/activemq/
11 [DebianBug]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562954
12 [SecurityWithActiveMQ]: /mcollective/reference/integration/activemq_security.html
13 [ActiveMQClustering]: http://www.devco.net/archives/2009/11/10/activemq_clustering.php
14 [ActiveMQSamples]: http://github.com/puppetlabs/marionette-collective/tree/master/ext/activemq/examples/
15 [ConfigurationReference]: /mcollective/reference/basic/configuration.html
16 [Terminology]: /mcollective/terminology.html
17 [SimpleRPCIntroduction]: /mcollective/simplerpc/
18 [ControllingTheDaemon]: /mcollective/reference/basic/daemon.html
19 [SSLSecurityPlugin]: /mcollective/reference/plugins/security_ssl.html
20 [AESSecurityPlugin]: /mcollective/reference/plugins/security_aes.html
21 [ConnectorActiveMQ]: /mcollective/reference/plugins/connector_activemq.html
22 [ConnectorRabbitMQ]: /mcollective/reference/plugins/connector_rabbitmq.html
23 [MessageFlowCast]: /mcollective/screencasts.html#message_flow
24 [Plugins]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
25 [RedHatGuide]: gettingstarted_redhat.html
26 [DebianGuide]: gettingstarted_debian.html
27 [server_config]: /mcollective/configure/server.html
29 *NOTE:* This is an older, deprecated version of 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]. Users on less common platforms should adapt one of those two instead of continuing to read this page.
31 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.
33 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.
36 We try to keep the requirements on external Gems to a minimum, you only need:
38 * A Stomp server, tested against [ActiveMQ] and [RabbitMQ]
41 * [Ruby Stomp Client][Stomp]
43 RPMs for these are available [here][DepRPMs].
46 ActiveMQ is currently the most used middleware for MCollective, it would be our recommended choice and one
47 that the community has most experience supporting. There is a specific connector for RabbitMQ if you wish
48 to go that route though - see [ConnectorRabbitMQ] for details. This guide will focus on ActiveMQ.
50 Full details on setting up and configuring ActiveMQ is out of scope for this, but you can follow these simple
51 setup instructions for initial testing (make sure JDK is installed, see below for Debian specific issue regarding JDK):
53 ### Download and Install
54 1. Download the ActiveMQ "binary" package (for Unix) from [ActiveMQ]
55 1. Extract the contents of the archive:
56 1. cd into the activemq directory
57 1. Execute the activemq binary
59 {% highlight console %}
60 % tar xvzf activemq-x.x.x.tar.gz
65 Below should help you get stomp and a user going. For their excellent full docs please see [ActiveMQ].
66 There are also tested configurations in [the ext directory][ActiveMQSamples]
68 A spec file can be found in the *ext* directory on GitHub that can be used to build RPMs for RedHat/CentOS/Fedora
69 you need *tanukiwrapper* which you can find from *jpackage*, it runs fine under OpenJDK that comes with recent
70 versions of these Operating Systems. I've uploaded some RPMs and SRPMs [here][DepRPMs].
72 For Debian systems you'd be better off using OpenJDK than Sun JDK, there's a known issue [#562954][DebianBug].
75 First you should configure ActiveMQ to listen on the Stomp protocol
77 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:
79 *Note: This config is for ActiveMQ 5.4*
83 xmlns="http://www.springframework.org/schema/beans"
84 xmlns:amq="http://activemq.apache.org/schema/core"
85 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
86 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
87 http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd
88 http://activemq.apache.org/camel/schema/spring http://activemq.apache.org/camel/schema/spring/camel-spring.xsd">
90 <broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" useJmx="true">
92 <managementContext createConnector="false"/>
96 <statisticsBrokerPlugin/>
97 <simpleAuthenticationPlugin>
99 <authenticationUser username="mcollective" password="marionette" groups="mcollective,everyone"/>
100 <authenticationUser username="admin" password="secret" groups="mcollective,admin,everyone"/>
102 </simpleAuthenticationPlugin>
103 <authorizationPlugin>
106 <authorizationEntries>
107 <authorizationEntry queue=">" write="admins" read="admins" admin="admins" />
108 <authorizationEntry topic=">" write="admins" read="admins" admin="admins" />
109 <authorizationEntry topic="mcollective.>" write="mcollective" read="mcollective" admin="mcollective" />
110 <authorizationEntry queue="mcollective.>" write="mcollective" read="mcollective" admin="mcollective" />
111 <authorizationEntry topic="ActiveMQ.Advisory.>" read="everyone" write="everyone" admin="everyone"/>
112 </authorizationEntries>
115 </authorizationPlugin>
121 <memoryUsage limit="20 mb"/>
124 <storeUsage limit="1 gb" name="foo"/>
127 <tempUsage limit="100 mb"/>
132 <transportConnectors>
133 <transportConnector name="openwire" uri="tcp://0.0.0.0:61616"/>
134 <transportConnector name="stomp" uri="stomp://0.0.0.0:61613"/>
135 </transportConnectors>
140 This creates a user *mcollective* with the password *marionette* and give it access to read/write/admin */topic/mcollective.`*`*.
142 Save the above code as activemq.xml and run activemq as - if installing from a package probably _/etc/activemq/activemq.xml_:
144 Else your package would have a RC script:
146 {% highlight console %}
147 # /etc/init.d/activemq start
150 For further info about ActiveMQ settings you might need see [SecurityWithActiveMQ] and [ActiveMQClustering].
152 There are also a few known to work and tested [configs in git][ActiveMQSamples].
156 ### Download and Extract
157 Grab a copy of the mcollective ideally you'd use a package for your distribution else there's a tarfile that
158 you can use, you can extract it wherever you want, the RPMs or deps will put files in Operating System compatible
159 locations. If you use the tarball you'll need to double check all the paths in the config files below.
162 You'll need to tweak some configs in */etc/mcollective/client.cfg*, a full reference of config settings can be
163 found [here][ConfigurationReference]:
165 Mostly what you'll need to change is the *identity*, *plugin.activemq.1.`*`* and the *plugin.psk*:
169 libdir = /usr/libexec/mcollective
174 # connector plugin config
176 plugin.activemq.pool.size = 1
177 plugin.activemq.pool.1.host = stomp.your.net
178 plugin.activemq.pool.1.port = 61613
179 plugin.activemq.pool.1.user = unset
180 plugin.activemq.pool.1.password = unset
182 # security plugin config
183 securityprovider = psk
184 plugin.psk = abcdefghj
187 You should also create _/etc/mcollective/server.cfg_ here's a sample, a full reference of config settings can be found on the [Server Configuration Reference][server_config]:
191 libdir = /usr/libexec/mcollective
192 logfile = /var/log/mcollective.log
198 registerinterval = 300
200 # connector plugin config
202 plugin.activemq.pool.size = 1
203 plugin.activemq.pool.1.host = stomp.your.net
204 plugin.activemq.pool.1.port = 61613
205 plugin.activemq.pool.1.user = mcollective
206 plugin.activemq.pool.1.password = password
210 plugin.yaml = /etc/mcollective/facts.yaml
212 # security plugin config
213 securityprovider = psk
214 plugin.psk = abcdefghj
217 Replace the *plugin.activemq.pool.1.host* with your server running ActiveMQ and replace the *plugin.psk* with a Pre-Shared Key of your own.
219 The ActiveMQ connector supports other options like failover pools, see [ConnectorActiveMQ] for full details.
222 By default - and for this setup - we'll use a simple YAML file for a fact source, later on you can use Puppet Labs Facter or something else.
224 Create */etc/mcollective/facts.yaml* along these lines:
233 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.
235 ### Test from a client
236 If all is setup you can test with the client code:
238 {% highlight console %}
240 your.domain.com time=74.41 ms
242 ---- ping statistics ----
243 1 replies max: 74.41 min: 74.41 avg: 74.41
246 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
247 would have seen several replies, be sure to give each a unique *identity* in the config.
249 At this point you can start exploring the discovery features for example:
251 {% highlight console %}
252 % mco find --with-fact country=uk
256 This searches all systems currently active for ones with a fact *country=uk*, it got the data from the yaml file you made earlier.
258 If you use configuration management tools like puppet and the nodes are setup with classes with *classes.txt* in */var/lib/puppet* then you
259 can search for nodes with a specific class on them - the locations will configurable soon:
261 {% highlight console %}
262 % mco find --with-class common::linux
266 Chef does not yet support such a list natively but we have some details on the wiki to achieve the same with Chef.
268 The filter commands are important they will be the main tool you use to target only parts of your infrastructure with calls to agents.
270 See the *--help* option to the various *mco `*`* commands for available options. You can now look at some of the available plugins and
271 play around, you might need to run the server process as root if you want to play with services etc.
274 We provide limited default plugins, you can look on our sister project [MCollective Plugins][Plugins] where you will
275 find various plugins to manage packages, services etc.
278 From here you should look at the rest of the wiki pages some key pages are:
280 * [Screencasts] - Get a hands-on look at what is possible
282 * [Introduction to Simple RPC][SimpleRPCIntroduction] - a simple to use framework for writing clients and agents
283 * [ControllingTheDaemon] - Controlling a running daemon
284 * [AESSecurityPlugin] - Using AES+RSA for secure message encryption and authentication of clients
285 * [SSLSecurityPlugin] - Using SSL for secure message signing and authentication of clients