website/reference/basic/gettingstarted_redhat.md

   1 ---
   2 layout: default
   3 title: Getting Started
   4 ---
   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 [ConnectorStomp]: /mcollective/reference/plugins/connector_stomp.html
  22 [MessageFlowCast]: /mcollective/screencasts.html#message_flow
  23 [Plugins]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
  24 [MCDownloads]: http://www.puppetlabs.com/downloads/mcollective/
  25 [EPEL]: http://fedoraproject.org/wiki/EPEL
  26
  27 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.
  28
  29 If you just want to experiment with the system please try our [EC2 based demo][EC2Demo].  You should be familiar with the architecture and terminology of Marionette Collective, please review the [basic architecture, terminology and message flow][MessageFlowCast] screencast first.
  30
  31 ## Requirements
  32 We try to keep the requirements on external Gems to a minimum, you only need:
  33
  34  * A Stomp server, tested against [ActiveMQ]
  35  * Ruby
  36  * Rubygems
  37  * [Ruby Stomp Client][Stomp]
  38
  39 ## Packages
  40
  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:
  42
  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
  46  * RubyGems - [EPEL]
  47  * Stomp Ruby Gem - [EPEL]
  48  * [MCollective][MCDownloads] - mcollective-1.x.x-1.el5.noarch.rpm, mcollective-common-1.x.x-1.el5.noarch.rpm, mcollective-client-1.x.x-1.el5.noarch.rpm
  49
  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_.
  51
  52 ## ActiveMQ
  53 ActiveMQ is currently the most used and tested middleware for use with MCollective.
  54
  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].
  57
  58 ### Install
  59
  60 On the server that you chose to configure as the ActiveMQ server:
  61
  62 {% highlight console %}
  63 % yum install java-1.6.0-openjdk activemq
  64 {% endhighlight %}
  65
  66 ### Configuring
  67
  68 Initially you'll just keep it simple with a single ActiveMQ broker and a basic user setup, further security information for ActiveMQ
  69 can be found [here][SecurityWithActiveMQ]
  70
  71 Place the following in _/etc/activemq/activemq.xml_ you can download this file from [GitHub][ActiveMQSingleBrokerSample]
  72
  73 Other examples are also available from [GitHub][ActiveMQSamples]
  74
  75 {% highlight xml %}
  76 <beans
  77   xmlns="http://www.springframework.org/schema/beans"
  78   xmlns:amq="http://activemq.apache.org/schema/core"
  79   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  80   xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
  81   http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd
  82   http://activemq.apache.org/camel/schema/spring http://activemq.apache.org/camel/schema/spring/camel-spring.xsd">
  83
  84     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" useJmx="true">
  85         <destinationPolicy>
  86           <policyMap>
  87             <policyEntries>
  88               <policyEntry topic=">" producerFlowControl="false"/>
  89               <policyEntry queue="*.reply.>" gcInactiveDestinations="true" inactiveTimoutBeforeGC="300000" />
  90             </policyEntries>
  91           </policyMap>
  92         </destinationPolicy>
  93
  94         <managementContext>
  95             <managementContext createConnector="false"/>
  96         </managementContext>
  97
  98         <plugins>
  99           <statisticsBrokerPlugin/>
 100           <simpleAuthenticationPlugin>
 101             <users>
 102               <authenticationUser username="mcollective" password="marionette" groups="mcollective,everyone"/>
 103               <authenticationUser username="admin" password="secret" groups="mcollective,admin,everyone"/>
 104             </users>
 105           </simpleAuthenticationPlugin>
 106           <authorizationPlugin>
 107             <map>
 108               <authorizationMap>
 109                 <authorizationEntries>
 110                   <authorizationEntry queue=">" write="admins" read="admins" admin="admins" />
 111                   <authorizationEntry topic=">" write="admins" read="admins" admin="admins" />
 112                   <authorizationEntry topic="mcollective.>" write="mcollective" read="mcollective" admin="mcollective" />
 113                   <authorizationEntry queue="mcollective.>" write="mcollective" read="mcollective" admin="mcollective" />
 114                   <authorizationEntry topic="ActiveMQ.Advisory.>" read="everyone" write="everyone" admin="everyone"/>
 115                 </authorizationEntries>
 116               </authorizationMap>
 117             </map>
 118           </authorizationPlugin>
 119         </plugins>
 120
 121         <systemUsage>
 122             <systemUsage>
 123                 <memoryUsage>
 124                     <memoryUsage limit="20 mb"/>
 125                 </memoryUsage>
 126                 <storeUsage>
 127                     <storeUsage limit="1 gb" name="foo"/>
 128                 </storeUsage>
 129                 <tempUsage>
 130                     <tempUsage limit="100 mb"/>
 131                 </tempUsage>
 132             </systemUsage>
 133         </systemUsage>
 134
 135         <transportConnectors>
 136             <transportConnector name="openwire" uri="tcp://0.0.0.0:61616"/>
 137             <transportConnector name="stomp" uri="stomp://0.0.0.0:61613"/>
 138         </transportConnectors>
 139     </broker>
 140 </beans>
 141 {% endhighlight %}
 142
 143 This creates a user *mcollective* with the password *marionette* and give it access to read/write/admin */topic/mcollective.`*`*.  You should change this passsword.
 144
 145 ### Starting
 146
 147 Start the ActiveMQ service:
 148
 149 {% highlight console %}
 150   # /etc/init.d/activemq start
 151 {% endhighlight %}
 152
 153 You should see it running in the process list:
 154
 155 {% highlight console %}
 156  # ps -auxw|grep java
 157  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
 158 {% endhighlight %}
 159
 160 You should also see it listening on port 61613 in your network stack
 161
 162 You should open port 61613 for all your nodes to connect to.
 163
 164 ## Marionette Collective
 165
 166 There are a few packages supplied and you will have potentially two type of server:
 167
 168  * Nodes that you wish to manage using mcollective need the mcollective and mcollective-common packages
 169  * Nodes that you wish to use to initiate requests from also known as clients need mcollective-client and mcollective-common packages
 170
 171 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.
 172
 173 ### Installation
 174
 175 {% highlight console %}
 176  # yum install mcollective mcollective-client mcollective-common rubygem-stomp
 177 {% endhighlight %}
 178
 179
 180 ## Configuring
 181 You'll need to tweak some configs in */etc/mcollective/client.cfg*, a full reference of config settings can be
 182 found [here][ConfigurationReference]:
 183
 184 We're assuming you called the machine running ActiveMQ *stomp.example.net* please change as appropriate
 185
 186 {% highlight ini %}
 187   # main config
 188   libdir = /usr/libexec/mcollective
 189   logfile = /dev/null
 190   loglevel = error
 191
 192   # connector plugin config
 193   connector = stomp
 194   plugin.stomp.host = stomp.example.net
 195   plugin.stomp.port = 61613
 196   plugin.stomp.user = mcollective
 197   plugin.stomp.password = marionette
 198
 199   # security plugin config
 200   securityprovider = psk
 201   plugin.psk = abcdefghj
 202 {% endhighlight %}
 203
 204 You should also create _/etc/mcollective/server.cfg_ here's a sample, , a full reference of config settings can be found here [ConfigurationReference]:
 205
 206 {% highlight ini %}
 207   # main config
 208   libdir = /usr/libexec/mcollective
 209   logfile = /var/log/mcollective.log
 210   daemonize = 1
 211   loglevel = info
 212
 213   # connector plugin config
 214   connector = stomp
 215   plugin.stomp.host = stomp.example.net
 216   plugin.stomp.port = 61613
 217   plugin.stomp.user = mcollective
 218   plugin.stomp.password = marionette
 219
 220   # facts
 221   factsource = yaml
 222   plugin.yaml = /etc/mcollective/facts.yaml
 223
 224   # security plugin config
 225   securityprovider = psk
 226   plugin.psk = abcdefghj
 227 {% endhighlight %}
 228
 229 Replace the *plugin.psk* in both these files with a Pre-Shared Key of your own.
 230
 231 ### Create Facts
 232 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.
 233
 234 Create */etc/mcollective/facts.yaml* along these lines:
 235
 236 {% highlight yaml %}
 237   ---
 238   location: devel
 239   country: uk
 240 {% endhighlight %}
 241
 242 ### Start the Server
 243
 244 The packages include standard init script, just start the server:
 245
 246 {% highlight console %}
 247   # /etc/init.d/mcollective restart
 248 {% endhighlight %}
 249
 250 You should see in the log file somethig like:
 251
 252 {% highlight console %}
 253   # tail /var/log/mcollective.log
 254   I, [2010-12-29T11:15:32.321744 #11479]  INFO -- : mcollectived:33 The Marionette Collective 1.1.0 started logging at info level
 255 {% endhighlight %}
 256
 257 ### Test connectivity
 258
 259 If all is fine and you see this log message you can test with the client code:
 260
 261 {% highlight console %}
 262 % mco ping
 263 your.domain.com                           time=74.41 ms
 264
 265 ---- ping statistics ----
 266 1 replies max: 74.41 min: 74.41 avg: 74.41
 267 {% endhighlight %}
 268
 269 This sends out a simple 'hello' packet to all the machines, as we only installed one you should have just one reply.
 270
 271 If you install the _mcollective_ and _mcollective-common_ packages along wit the facts and server.cfg you should see more nodes show up here.
 272
 273 You can explore other aspects of your machines:
 274
 275 {% highlight console %}
 276 % mco find --with-fact country=uk
 277 your.domain.com
 278 {% endhighlight %}
 279
 280 This searches all systems currently active for ones with a fact *country=uk*, it got the data from the yaml file you made earlier.
 281
 282 If you use confiuration management tools like puppet and the nodes are setup with classes with *classes.txt* in */var/lib/puppet* then you
 283 can search for nodes with a specific class on them - the locations will configurable soon:
 284
 285 {% highlight console %}
 286 % mco find --with-class common::linux
 287 your.domain.com
 288 {% endhighlight %}
 289
 290 The filter commands are important they will be the main tool you use to target only parts of your infrastructure with calls to agents.
 291
 292 See the *--help* option to the various *mco `*`* commands for available options.  You can now look at some of the available plugins and
 293 play around, you might need to run the server process as root if you want to play with services etc.
 294
 295 ### Plugins
 296 We provide limited default plugins, you can look on our sister project [MCollective Plugins][Plugins] where you will
 297 find various plugins to manage packages, services etc.
 298
 299 ### Further Reading
 300 From here you should look at the rest of the wiki pages some key pages are:
 301
 302  * [Screencasts] - Get a hands-on look at what is possible
 303  * [Terminology]
 304  * [Introduction to Simple RPC][SimpleRPCIntroduction] - a simple to use framework for writing clients and agents
 305  * [ControllingTheDaemon] - Controlling a running daemon
 306  * [AESSecurityPlugin] - Using AES+RSA for secure message encryption and authentication of clients
 307  * [SSLSecurityPlugin] - Using SSL for secure message signing and authentication of clients
 308  * [ConnectorStomp] - Full details on the Stomp adapter including failover pools