website/reference/basic/gettingstarted_debian.md

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