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]: /mcollective/reference/integration/activemq_clusters.html
13 [ActiveMQSamples]: http://github.com/puppetlabs/marionette-collective/tree/master/ext/activemq/examples/
14 [ActiveMQSingleBrokerSample]: http://github.com/puppetlabs/marionette-collective/raw/master/ext/activemq/examples/single-broker/activemq.xml
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 [MCDownloads]: http://www.puppetlabs.com/downloads/mcollective/
26 [EPEL]: http://fedoraproject.org/wiki/EPEL
27 [server_config]: /mcollective/configure/server.html
29 Getting started using Red Hat based distribution like Red Hat Enterprise Linux and CentOS is easy as RPMs are available for all the required components. This guide walks you through the process.
32 We try to keep the requirements on external Gems to a minimum, you only need:
34 * A Stomp server, tested against [ActiveMQ]
37 * [Ruby Stomp Client][Stomp]
41 We strongly recommend you set up a local Yum repository that will host all the packages on your LAN, you can get the prerequisite packages here:
43 * [ActiveMQ][MCDownloads] - activemq-5.4.0-2.el5.noarch.rpm, activemq-info-provider-5.4.0-2.el5.noarch.rpm, tanukiwrapper-3.2.3-1jpp.`*`.rpm
44 * Java - OpenJDK that is included with your distribution
45 * Ruby - included with your distribution
47 * Stomp Ruby Gem - [EPEL]
48 * [MCollective][MCDownloads] - mcollective-2.2.x-1.el5.noarch.rpm, mcollective-common-2.2.x-1.el5.noarch.rpm, mcollective-client-2.2.x-1.el5.noarch.rpm
50 The rest of this guide will assume you set up a Yum repository. Puppet Labs hosts a Yum repository with all these dependencies at _yum.puppetlabs.com_.
53 ActiveMQ is currently the most used and tested middleware for use with MCollective.
55 You need at least one ActiveMQ server on your network, all the nodes you wish to manage will connect to the central ActiveMQ server.
56 Later on your can [cluster the ActiveMQ servers for availability and scale][ActiveMQClustering].
60 On the server that you chose to configure as the ActiveMQ server:
62 {% highlight console %}
63 % yum install java-1.6.0-openjdk activemq
68 [The ActiveMQ config reference][activemq_config] describes all of the ActiveMQ settings that MCollective cares about. For best use, skim the sections you care about while comparing it to an example activemq.xml file.
70 [activemq_config]: /mcollective/deploy/middleware/activemq.html
72 We recommend that new users:
74 * Start with the [single-broker example config][ActiveMQSingleBrokerSample].
75 * Change the [user account passwords](/mcollective/deploy/middleware/activemq.html#authentication-users-and-groups).
76 * [Set up TLS](/mcollective/deploy/middleware/activemq.html#tls-credentials) and [use a TLS Stomp transport connector](/mcollective/deploy/middleware/activemq.html#transport-connectors).
78 Other example config files are also available from [GitHub][ActiveMQSamples].
83 Start the ActiveMQ service:
85 {% highlight console %}
86 # /etc/init.d/activemq start
89 You should see it running in the process list:
91 {% highlight console %}
93 activemq 3012 0.1 14.5 1155112 152180 ? Sl Dec28 2:02 java -Dactivemq.home=/usr/share/activemq -Dactivemq.base=/usr/share/activemq -Dcom.sun.management.jmxremote -Dorg.apache.activemq.UseDedicatedTaskRunner=true -Xmx512m -Djava.library.path=/usr/lib:/usr/lib64 -classpath /usr/share/java/tanukiwrapper.jar:/usr/share/activemq/bin/run.jar -Dwrapper.key=eg4_VvENzCmvtAKg -Dwrapper.port=32000 -Dwrapper.jvm.port.min=31000 -Dwrapper.jvm.port.max=31999 -Dwrapper.pid=3000 -Dwrapper.version=3.2.3 -Dwrapper.native_library=wrapper -Dwrapper.service=TRUE -Dwrapper.cpu.timeout=10 -Dwrapper.jvmid=1 org.tanukisoftware.wrapper.WrapperSimpleApp org.apache.activemq.console.Main start
96 You should also see it listening on port 61613 in your network stack
98 You should open port 61613 for all your nodes to connect to.
100 ## Marionette Collective
102 There are a few packages supplied and you will have potentially two type of server:
104 * Nodes that you wish to manage using mcollective need the mcollective and mcollective-common packages
105 * Nodes that you wish to use to initiate requests from also known as clients need mcollective-client and mcollective-common packages
107 A machine can be both at once, in which case you need to install all 3 packages. We'll work on the assumption here that you wish to both manage your machine and use it as a client by installing all 3 packages on our initial node.
111 {% highlight console %}
112 # yum install mcollective mcollective-client mcollective-common rubygem-stomp
117 You'll need to tweak some configs in */etc/mcollective/client.cfg*, a full reference of config settings can be
118 found [here][ConfigurationReference]:
120 We're assuming you called the machine running ActiveMQ *stomp.example.net* please change as appropriate
124 libdir = /usr/libexec/mcollective
128 # connector plugin config
130 plugin.activemq.pool.size = 1
131 plugin.activemq.pool.1.host = stomp.example.net
132 plugin.activemq.pool.1.port = 61613
133 plugin.activemq.pool.1.user = mcollective
134 plugin.activemq.pool.1.password = marionette
136 # security plugin config
137 securityprovider = psk
138 plugin.psk = abcdefghj
141 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]:
145 libdir = /usr/libexec/mcollective
146 logfile = /var/log/mcollective.log
150 # connector plugin config
152 plugin.activemq.pool.size = 1
153 plugin.activemq.pool.1.host = stomp.example.net
154 plugin.activemq.pool.1.port = 61613
155 plugin.activemq.pool.1.user = mcollective
156 plugin.activemq.pool.1.password = marionette
160 plugin.yaml = /etc/mcollective/facts.yaml
162 # security plugin config
163 securityprovider = psk
164 plugin.psk = abcdefghj
167 Replace the *plugin.psk* in both these files with a Pre-Shared Key of your own.
170 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.
172 Create */etc/mcollective/facts.yaml* along these lines:
182 The packages include standard init script, just start the server:
184 {% highlight console %}
185 # /etc/init.d/mcollective restart
188 You should see in the log file somethig like:
190 {% highlight console %}
191 # tail /var/log/mcollective.log
192 I, [2010-12-29T11:15:32.321744 #11479] INFO -- : mcollectived:33 The Marionette Collective 1.1.0 started logging at info level
195 ### Test connectivity
197 If all is fine and you see this log message you can test with the client code:
199 {% highlight console %}
201 your.domain.com time=74.41 ms
203 ---- ping statistics ----
204 1 replies max: 74.41 min: 74.41 avg: 74.41
207 This sends out a simple 'hello' packet to all the machines, as we only installed one you should have just one reply.
209 If you install the _mcollective_ and _mcollective-common_ packages along wit the facts and server.cfg you should see more nodes show up here.
211 You can explore other aspects of your machines:
213 {% highlight console %}
214 % mco find --with-fact country=uk
218 This searches all systems currently active for ones with a fact *country=uk*, it got the data from the yaml file you made earlier.
220 If you use confiuration management tools like puppet and the nodes are setup with classes with *classes.txt* in */var/lib/puppet* then you
221 can search for nodes with a specific class on them - the locations will configurable soon:
223 {% highlight console %}
224 % mco find --with-class common::linux
228 The filter commands are important they will be the main tool you use to target only parts of your infrastructure with calls to agents.
230 See the *--help* option to the various *mco `*`* commands for available options. You can now look at some of the available plugins and
231 play around, you might need to run the server process as root if you want to play with services etc.
234 We provide limited default plugins, you can look on our sister project [MCollective Plugins][Plugins] where you will
235 find various plugins to manage packages, services etc.
238 From here you should look at the rest of the wiki pages some key pages are:
240 * [Screencasts] - Get a hands-on look at what is possible
242 * [Introduction to Simple RPC][SimpleRPCIntroduction] - a simple to use framework for writing clients and agents
243 * [ControllingTheDaemon] - Controlling a running daemon
244 * [AESSecurityPlugin] - Using AES+RSA for secure message encryption and authentication of clients
245 * [SSLSecurityPlugin] - Using SSL for secure message signing and authentication of clients