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 [ConnectorActiveMQ]: /mcollective/reference/plugins/connector_activemq.html
  23 [ConnectorRabbitMQ]: /mcollective/reference/plugins/connector_rabbitmq.html
  24 [MessageFlowCast]: /mcollective/screencasts.html#message_flow
  25 [Plugins]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
  26 [MCDownloads]: http://www.puppetlabs.com/downloads/mcollective/
  27 [RubyGems]: http://packages.debian.org/search?suite=default&section=all&arch=any&searchon=names&keywords=rubygems
  28 [server_config]: /mcollective/configure/server.html
  29
  30 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.
  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-2.2.x-1_all.deb, mcollective-common-2.2.x-1_all.deb, mcollective-client-2.2.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
  55 ActiveMQ is currently the most used and tested middleware for use with MCollective.
  56
  57 You need at least one ActiveMQ server on your network, all the nodes you wish to manage will connect to the central ActiveMQ server.
  58 Later on you can [cluster the ActiveMQ servers for availability and scale][ActiveMQClustering].
  59
  60 ### Install
  61
  62 On the server that you chose to configure as the ActiveMQ server:
  63
  64 {% highlight console %}
  65 % apt-get install openjdk-6-jre
  66 {% endhighlight %}
  67
  68 ActiveMQ installation instructions can be found [here][ActiveMQ Getting Started].
  69
  70 ### Configuring
  71
  72 [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.
  73
  74 [activemq_config]: /mcollective/deploy/middleware/activemq.html
  75
  76 We recommend that new users:
  77
  78 * Start with the [single-broker example config][ActiveMQSingleBrokerSample].
  79 * Change the [user account passwords](/mcollective/deploy/middleware/activemq.html#authentication-users-and-groups).
  80 * [Set up TLS](/mcollective/deploy/middleware/activemq.html#tls-credentials) and [use a TLS Stomp transport connector](/mcollective/deploy/middleware/activemq.html#transport-connectors).
  81
  82 Other example config files are also available from [GitHub][ActiveMQSamples].
  83
  84 ### Starting
  85
  86 Start the ActiveMQ service:
  87
  88 {% highlight console %}
  89   # /etc/init.d/activemq start
  90 {% endhighlight %}
  91
  92 You should see it running in the process list:
  93
  94 {% highlight console %}
  95  # ps auxw|grep java
  96  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
  97 {% endhighlight %}
  98
  99 You should also see it listening on port 61613 or 61614 in your network stack, depending on whether you turned on TLS.
 100
 101 You should open port 61613 or 61614 for all your nodes to connect to.
 102
 103 ## Marionette Collective
 104
 105 There are a few packages supplied and you will have potentially two type of server:
 106
 107  * Nodes that you wish to manage using mcollective need the mcollective and mcollective-common packages
 108  * Nodes that you wish to use to initiate requests from also known as clients need mcollective-client and mcollective-common packages
 109
 110 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
 112 ### Installation
 113
 114 {% highlight console %}
 115   # apt-get install mcollective mcollective-client mcollective-common
 116   # gem install stomp
 117 {% endhighlight %}
 118
 119
 120 ## Configuring
 121 You'll need to tweak some configs in */etc/mcollective/client.cfg*, a full reference of config settings can be
 122 found [here][ConfigurationReference]:
 123
 124 We're assuming you called the machine running ActiveMQ *stomp.example.net*; please change as appropriate. Also note that the port should be 61614 if you turned on TLS.
 125
 126 {% highlight ini %}
 127   # main config
 128   libdir = /usr/libexec/mcollective
 129   logfile = /dev/null
 130   loglevel = error
 131
 132   # connector plugin config
 133   connector = activemq
 134   plugin.activemq.pool.size = 1
 135   plugin.activemq.pool.1.host = stomp.example.net
 136   plugin.activemq.pool.1.port = 61613
 137   plugin.activemq.pool.1.user = mcollective
 138   plugin.activemq.pool.1.password = marionette
 139
 140   # security plugin config
 141   securityprovider = psk
 142   plugin.psk = abcdefghj
 143 {% endhighlight %}
 144
 145 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]:
 146
 147 {% highlight ini %}
 148   # main config
 149   libdir = /usr/libexec/mcollective
 150   logfile = /var/log/mcollective.log
 151   daemonize = 1
 152   loglevel = info
 153
 154   # connector plugin config
 155   connector = activemq
 156   plugin.activemq.pool.size = 1
 157   plugin.activemq.pool.1.host = stomp.example.net
 158   plugin.activemq.pool.1.port = 61613
 159   plugin.activemq.pool.1.user = mcollective
 160   plugin.activemq.pool.1.password = marionette
 161
 162
 163   # facts
 164   factsource = yaml
 165   plugin.yaml = /etc/mcollective/facts.yaml
 166
 167   # security plugin config
 168   securityprovider = psk
 169   plugin.psk = abcdefghj
 170 {% endhighlight %}
 171
 172 Replace the *plugin.psk* in both these files with a Pre-Shared Key of your own.
 173
 174 ### Create Facts
 175 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.
 176
 177 Create */etc/mcollective/facts.yaml* along these lines:
 178
 179 {% highlight yaml %}
 180   ---
 181   location: devel
 182   country: uk
 183 {% endhighlight %}
 184
 185 ### Start the Server
 186
 187 The packages include standard init script, just start the server:
 188
 189 {% highlight console %}
 190   # /etc/init.d/mcollective restart
 191 {% endhighlight %}
 192
 193 You should see in the log file somethig like:
 194
 195 {% highlight console %}
 196   # tail /var/log/mcollective.log
 197   I, [2010-12-29T11:15:32.321744 #11479]  INFO -- : mcollectived:33 The Marionette Collective 1.1.0 started logging at info level
 198 {% endhighlight %}
 199
 200 ### Test connectivity
 201
 202 If all is fine and you see this log message you can test with the client code:
 203
 204 {% highlight console %}
 205 % mco ping
 206 your.domain.com                           time=74.41 ms
 207
 208 ---- ping statistics ----
 209 1 replies max: 74.41 min: 74.41 avg: 74.41
 210 {% endhighlight %}
 211
 212 This sends out a simple 'hello' packet to all the machines, as we only installed one you should have just one reply.
 213
 214 If you install the _mcollective_ and _mcollective-common_ packages along wit the facts and server.cfg you should see more nodes show up here.
 215
 216 You can explore other aspects of your machines:
 217
 218 {% highlight console %}
 219 % mco find --with-fact country=uk
 220 your.domain.com
 221 {% endhighlight %}
 222
 223 This searches all systems currently active for ones with a fact *country=uk*, it got the data from the yaml file you made earlier.
 224
 225 If you use confiuration management tools like puppet and the nodes are setup with classes with *classes.txt* in */var/lib/puppet* then you
 226 can search for nodes with a specific class on them - the locations will configurable soon:
 227
 228 {% highlight console %}
 229 % mco find --with-class common::linux
 230 your.domain.com
 231 {% endhighlight %}
 232
 233 The filter commands are important they will be the main tool you use to target only parts of your infrastructure with calls to agents.
 234
 235 See the *--help* option to the various *mco `*`* commands for available options.  You can now look at some of the available plugins and
 236 play around, you might need to run the server process as root if you want to play with services etc.
 237
 238 ### Plugins
 239 We provide limited default plugins, you can look on our sister project [MCollective Plugins][Plugins] where you will
 240 find various plugins to manage packages, services etc.
 241
 242 ### Further Reading
 243 From here you should look at the rest of the wiki pages some key pages are:
 244
 245  * [Screencasts] - Get a hands-on look at what is possible
 246  * [Terminology]
 247  * [Introduction to Simple RPC][SimpleRPCIntroduction] - a simple to use framework for writing clients and agents
 248  * [ControllingTheDaemon] - Controlling a running daemon
 249  * [AESSecurityPlugin] - Using AES+RSA for secure message encryption and authentication of clients
 250  * [SSLSecurityPlugin] - Using SSL for secure message signing and authentication of clients