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 [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
  28
  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.
  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-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
  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 [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.
  69
  70 [activemq_config]: /mcollective/deploy/middleware/activemq.html
  71
  72 We recommend that new users:
  73
  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).
  77
  78 Other example config files are also available from [GitHub][ActiveMQSamples].
  79
  80
  81 ### Starting
  82
  83 Start the ActiveMQ service:
  84
  85 {% highlight console %}
  86   # /etc/init.d/activemq start
  87 {% endhighlight %}
  88
  89 You should see it running in the process list:
  90
  91 {% highlight console %}
  92  # ps auxw|grep java
  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
  94 {% endhighlight %}
  95
  96 You should also see it listening on port 61613 in your network stack
  97
  98 You should open port 61613 for all your nodes to connect to.
  99
 100 ## Marionette Collective
 101
 102 There are a few packages supplied and you will have potentially two type of server:
 103
 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
 106
 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.
 108
 109 ### Installation
 110
 111 {% highlight console %}
 112  # yum install mcollective mcollective-client mcollective-common rubygem-stomp
 113 {% endhighlight %}
 114
 115
 116 ## Configuring
 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]:
 119
 120 We're assuming you called the machine running ActiveMQ *stomp.example.net* please change as appropriate
 121
 122 {% highlight ini %}
 123   # main config
 124   libdir = /usr/libexec/mcollective
 125   logfile = /dev/null
 126   loglevel = error
 127
 128   # connector plugin config
 129   connector = activemq
 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
 135
 136   # security plugin config
 137   securityprovider = psk
 138   plugin.psk = abcdefghj
 139 {% endhighlight %}
 140
 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]:
 142
 143 {% highlight ini %}
 144   # main config
 145   libdir = /usr/libexec/mcollective
 146   logfile = /var/log/mcollective.log
 147   daemonize = 1
 148   loglevel = info
 149
 150   # connector plugin config
 151   connector = activemq
 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
 157
 158   # facts
 159   factsource = yaml
 160   plugin.yaml = /etc/mcollective/facts.yaml
 161
 162   # security plugin config
 163   securityprovider = psk
 164   plugin.psk = abcdefghj
 165 {% endhighlight %}
 166
 167 Replace the *plugin.psk* in both these files with a Pre-Shared Key of your own.
 168
 169 ### Create Facts
 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.
 171
 172 Create */etc/mcollective/facts.yaml* along these lines:
 173
 174 {% highlight yaml %}
 175   ---
 176   location: devel
 177   country: uk
 178 {% endhighlight %}
 179
 180 ### Start the Server
 181
 182 The packages include standard init script, just start the server:
 183
 184 {% highlight console %}
 185   # /etc/init.d/mcollective restart
 186 {% endhighlight %}
 187
 188 You should see in the log file somethig like:
 189
 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
 193 {% endhighlight %}
 194
 195 ### Test connectivity
 196
 197 If all is fine and you see this log message you can test with the client code:
 198
 199 {% highlight console %}
 200 % mco ping
 201 your.domain.com                           time=74.41 ms
 202
 203 ---- ping statistics ----
 204 1 replies max: 74.41 min: 74.41 avg: 74.41
 205 {% endhighlight %}
 206
 207 This sends out a simple 'hello' packet to all the machines, as we only installed one you should have just one reply.
 208
 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.
 210
 211 You can explore other aspects of your machines:
 212
 213 {% highlight console %}
 214 % mco find --with-fact country=uk
 215 your.domain.com
 216 {% endhighlight %}
 217
 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.
 219
 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:
 222
 223 {% highlight console %}
 224 % mco find --with-class common::linux
 225 your.domain.com
 226 {% endhighlight %}
 227
 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.
 229
 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.
 232
 233 ### Plugins
 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.
 236
 237 ### Further Reading
 238 From here you should look at the rest of the wiki pages some key pages are:
 239
 240  * [Screencasts] - Get a hands-on look at what is possible
 241  * [Terminology]
 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