X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;ds=sidebyside;f=website%2Freference%2Fbasic%2Fgettingstarted.md;fp=website%2Freference%2Fbasic%2Fgettingstarted.md;h=0000000000000000000000000000000000000000;hb=d1f1649ba43c5cbc43c4beb2380096ba051d646a;hp=bd1755de8a127f6f0796a92f15da68d93280d9cc;hpb=8a3fe7daeecccf43dd71c59371c5005400d35101;p=packages%2Fprecise%2Fmcollective.git diff --git a/website/reference/basic/gettingstarted.md b/website/reference/basic/gettingstarted.md deleted file mode 100644 index bd1755d..0000000 --- a/website/reference/basic/gettingstarted.md +++ /dev/null @@ -1,285 +0,0 @@ ---- -layout: default -title: Getting Started ---- -[Screencasts]: /mcollective/screencasts.html -[ActiveMQ]: http://activemq.apache.org/ -[RabbitMQ]: http://www.rabbitmq.com/ -[EC2Demo]: /mcollective/ec2demo.html -[Stomp]: http://stomp.codehaus.org/Ruby+Client -[DepRPMs]: http://www.marionette-collective.org/activemq/ -[DebianBug]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562954 -[SecurityWithActiveMQ]: /mcollective/reference/integration/activemq_security.html -[ActiveMQClustering]: http://www.devco.net/archives/2009/11/10/activemq_clustering.php -[ActiveMQSamples]: http://github.com/puppetlabs/marionette-collective/tree/master/ext/activemq/examples/ -[ConfigurationReference]: /mcollective/reference/basic/configuration.html -[Terminology]: /mcollective/terminology.html -[SimpleRPCIntroduction]: /mcollective/simplerpc/ -[ControllingTheDaemon]: /mcollective/reference/basic/daemon.html -[SSLSecurityPlugin]: /mcollective/reference/plugins/security_ssl.html -[AESSecurityPlugin]: /mcollective/reference/plugins/security_aes.html -[ConnectorActiveMQ]: /mcollective/reference/plugins/connector_activemq.html -[ConnectorRabbitMQ]: /mcollective/reference/plugins/connector_rabbitmq.html -[MessageFlowCast]: /mcollective/screencasts.html#message_flow -[Plugins]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki -[RedHatGuide]: gettingstarted_redhat.html -[DebianGuide]: gettingstarted_debian.html -[server_config]: /mcollective/configure/server.html - -*NOTE:* This is an older, deprecated version of the Getting Started documentation. Red Hat and CentOS users can refer to [our Redhat guide][RedHatGuide]. Debian users can refer to [our Debian guide][DebianGuide]. Users on less common platforms should adapt one of those two instead of continuing to read this page. - -Below find a rough guide to get you going, this assumes the client and server is on the same node, but servers don't need the client code installed. - -Look at the [Screencasts] page, there are [some screencasts dealing with basic architecture, terminology and so forth][MessageFlowCast] that you might find helpful before getting started. - -## Requirements -We try to keep the requirements on external Gems to a minimum, you only need: - - * A Stomp server, tested against [ActiveMQ] and [RabbitMQ] - * Ruby - * Rubygems - * [Ruby Stomp Client][Stomp] - -RPMs for these are available [here][DepRPMs]. - -## ActiveMQ -ActiveMQ is currently the most used middleware for MCollective, it would be our recommended choice and one -that the community has most experience supporting. There is a specific connector for RabbitMQ if you wish -to go that route though - see [ConnectorRabbitMQ] for details. This guide will focus on ActiveMQ. - -Full details on setting up and configuring ActiveMQ is out of scope for this, but you can follow these simple -setup instructions for initial testing (make sure JDK is installed, see below for Debian specific issue regarding JDK): - -### Download and Install - 1. Download the ActiveMQ "binary" package (for Unix) from [ActiveMQ] - 1. Extract the contents of the archive: - 1. cd into the activemq directory - 1. Execute the activemq binary - -{% highlight console %} - % tar xvzf activemq-x.x.x.tar.gz - % cd activemq-x.x.x - % bin/activemq -{% endhighlight %} - -Below should help you get stomp and a user going. For their excellent full docs please see [ActiveMQ]. -There are also tested configurations in [the ext directory][ActiveMQSamples] - -A spec file can be found in the *ext* directory on GitHub that can be used to build RPMs for RedHat/CentOS/Fedora -you need *tanukiwrapper* which you can find from *jpackage*, it runs fine under OpenJDK that comes with recent -versions of these Operating Systems. I've uploaded some RPMs and SRPMs [here][DepRPMs]. - -For Debian systems you'd be better off using OpenJDK than Sun JDK, there's a known issue [#562954][DebianBug]. - -### Configuring Stomp -First you should configure ActiveMQ to listen on the Stomp protocol - -And then you should add a user or two, to keep it simple we'll just add one user, the template file will hopefully make it obvious where this goes, it should be in the _broker_ block: - -*Note: This config is for ActiveMQ 5.4* - -{% highlight xml %} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -{% endhighlight %} - -This creates a user *mcollective* with the password *marionette* and give it access to read/write/admin */topic/mcollective.`*`*. - -Save the above code as activemq.xml and run activemq as - if installing from a package probably _/etc/activemq/activemq.xml_: - -Else your package would have a RC script: - -{% highlight console %} -# /etc/init.d/activemq start -{% endhighlight %} - -For further info about ActiveMQ settings you might need see [SecurityWithActiveMQ] and [ActiveMQClustering]. - -There are also a few known to work and tested [configs in git][ActiveMQSamples]. - -## mcollective - -### Download and Extract -Grab a copy of the mcollective ideally you'd use a package for your distribution else there's a tarfile that -you can use, you can extract it wherever you want, the RPMs or deps will put files in Operating System compatible -locations. If you use the tarball you'll need to double check all the paths in the config files below. - -### Configure -You'll need to tweak some configs in */etc/mcollective/client.cfg*, a full reference of config settings can be -found [here][ConfigurationReference]: - -Mostly what you'll need to change is the *identity*, *plugin.activemq.1.`*`* and the *plugin.psk*: - -{% highlight ini %} - # main config - libdir = /usr/libexec/mcollective - logfile = /dev/null - loglevel = debug - identity = fqdn - - # connector plugin config - connector = activemq - plugin.activemq.pool.size = 1 - plugin.activemq.pool.1.host = stomp.your.net - plugin.activemq.pool.1.port = 61613 - plugin.activemq.pool.1.user = unset - plugin.activemq.pool.1.password = unset - - # security plugin config - securityprovider = psk - plugin.psk = abcdefghj -{% endhighlight %} - -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]: - -{% highlight ini %} - # main config - libdir = /usr/libexec/mcollective - logfile = /var/log/mcollective.log - daemonize = 1 - keeplogs = 1 - max_log_size = 10240 - loglevel = debug - identity = fqdn - registerinterval = 300 - - # connector plugin config - connector = activemq - plugin.activemq.pool.size = 1 - plugin.activemq.pool.1.host = stomp.your.net - plugin.activemq.pool.1.port = 61613 - plugin.activemq.pool.1.user = mcollective - plugin.activemq.pool.1.password = password - - # facts - factsource = yaml - plugin.yaml = /etc/mcollective/facts.yaml - - # security plugin config - securityprovider = psk - plugin.psk = abcdefghj -{% endhighlight %} - -Replace the *plugin.activemq.pool.1.host* with your server running ActiveMQ and replace the *plugin.psk* with a Pre-Shared Key of your own. - -The ActiveMQ connector supports other options like failover pools, see [ConnectorActiveMQ] for full details. - -### Create Facts -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. - -Create */etc/mcollective/facts.yaml* along these lines: - -{% highlight yaml %} - --- - location: devel - country: uk -{% endhighlight %} - -### Start the Server -If you installed from a package start it with the RC script, else look in the source you'll find a LSB compatible RC script to start it. - -### Test from a client -If all is setup you can test with the client code: - -{% highlight console %} -% mco ping -your.domain.com time=74.41 ms - ----- ping statistics ---- -1 replies max: 74.41 min: 74.41 avg: 74.41 -{% endhighlight %} - -This sent a simple 'hello' packet out to the network and if you started up several of the *mcollectived.rb* processes on several machines you -would have seen several replies, be sure to give each a unique *identity* in the config. - -At this point you can start exploring the discovery features for example: - -{% highlight console %} -% mco find --with-fact country=uk -your.domain.com -{% endhighlight %} - -This searches all systems currently active for ones with a fact *country=uk*, it got the data from the yaml file you made earlier. - -If you use configuration management tools like puppet and the nodes are setup with classes with *classes.txt* in */var/lib/puppet* then you -can search for nodes with a specific class on them - the locations will configurable soon: - -{% highlight console %} -% mco find --with-class common::linux -your.domain.com -{% endhighlight %} - -Chef does not yet support such a list natively but we have some details on the wiki to achieve the same with Chef. - -The filter commands are important they will be the main tool you use to target only parts of your infrastructure with calls to agents. - -See the *--help* option to the various *mco `*`* commands for available options. You can now look at some of the available plugins and -play around, you might need to run the server process as root if you want to play with services etc. - -### Plugins -We provide limited default plugins, you can look on our sister project [MCollective Plugins][Plugins] where you will -find various plugins to manage packages, services etc. - -### Further Reading -From here you should look at the rest of the wiki pages some key pages are: - - * [Screencasts] - Get a hands-on look at what is possible - * [Terminology] - * [Introduction to Simple RPC][SimpleRPCIntroduction] - a simple to use framework for writing clients and agents - * [ControllingTheDaemon] - Controlling a running daemon - * [AESSecurityPlugin] - Using AES+RSA for secure message encryption and authentication of clients - * [SSLSecurityPlugin] - Using SSL for secure message signing and authentication of clients