X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=website%2Freference%2Fbasic%2Fgettingstarted.md;fp=website%2Freference%2Fbasic%2Fgettingstarted.md;h=6a36e6cb0f05179fe3f5278f08940087135c24c5;hb=b87d2f4e68281062df1913440ca5753ae63314a9;hp=0000000000000000000000000000000000000000;hpb=ab0ea530b8ac956091f17b104ab2311336cfc250;p=packages%2Fprecise%2Fmcollective.git diff --git a/website/reference/basic/gettingstarted.md b/website/reference/basic/gettingstarted.md new file mode 100644 index 0000000..6a36e6c --- /dev/null +++ b/website/reference/basic/gettingstarted.md @@ -0,0 +1,283 @@ +--- +layout: default +title: Getting Started +--- +[Screencasts]: /mcollective/screencasts.html +[ActiveMQ]: http://activemq.apache.org/ +[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 +[ConnectorStomp]: /mcollective/reference/plugins/connector_stomp.html +[MessageFlowCast]: /mcollective/screencasts.html#message_flow +[Plugins]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki +[RedHatGuide]: gettingstarted_redhat.html +[DebianGuide]: gettingstarted_debian.html + +*NOTE:* We are currently improving 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]. + +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. + +For an even quicker intro to how it all works you can try our [EC2 based demo][EC2Demo] + +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] + * Ruby + * Rubygems + * [Ruby Stomp Client][Stomp] + +RPMs for these are available [here][DepRPMs]. + +## ActiveMQ +I've developed this against ActiveMQ. It should work against other Stomp servers but I suspect if you choose +one without username and password support you might have problems, please let me know if that's the case +and I'll refactor the code around that. + +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.stomp.`*`* and the *plugin.psk*: + +{% highlight ini %} + # main config + libdir = /usr/libexec/mcollective + logfile = /dev/null + loglevel = debug + identity = fqdn + + # connector plugin config + connector = stomp + plugin.stomp.host = stomp.your.net + plugin.stomp.port = 6163 + plugin.stomp.user = unset + plugin.stomp.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 here [ConfigurationReference]: + +{% 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 = stomp + plugin.stomp.host = stomp.your.net + plugin.stomp.port = 6163 + plugin.stomp.user = mcollective + plugin.stomp.password = password + + # facts + factsource = yaml + plugin.yaml = /etc/mcollective/facts.yaml + + # security plugin config + securityprovider = psk + plugin.psk = abcdefghj +{% endhighlight %} + +Replace the *plugin.stomp.host* with your server running ActiveMQ and replace the *plugin.psk* with a Pre-Shared Key of your own. + +The STOMP connector supports other options like failover pools, see [ConnectorStomp] 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 Reductive 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 confiuration 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 + * [ConnectorStomp] - Full details on the Stomp adapter including failover pools