website/reference/plugins/registration.md

   1 ---
   2 layout: default
   3 title: Registration
   4 toc: false
   5 ---
   6 [RegistrationMonitor]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/AgentRegistrationMonitor
   7
   8 MCollective supports the ability for each node to register with a central inventory. The core functionality
   9 of Mcollective doesn't require registration internally; it's simply provided as a framework to enable you to
  10 build inventory systems or Web UIs.
  11
  12 ## Details
  13
  14 Registration plugins are easy to write. You can configure your nodes to use your own or the provided one.
  15
  16 The one we provide simply sends a list of agents to the inventory. It's available in the plugins directory
  17 under *registration/agentlist.rb* and can be seen in its entirety below:
  18
  19 {% highlight ruby %}
  20 module MCollective
  21     module Registration
  22         # A registration plugin that simply sends in the list of agents we have
  23         class Agentlist<Base
  24             def body
  25                 MCollective::Agents.agentlist
  26             end
  27         end
  28     end
  29 end
  30 {% endhighlight %}
  31
  32 You can see it's very simple, you just need to subclass *MCollective::Registration::Base* to ensure they get
  33 loaded into the plugin system and provide a _body_ method whose return value will be sent to the registration agent(s).
  34
  35 The registration plugin can decide if a message should be sent or not.  If your plugin responds with a _nil_ value the
  36 message will not be sent.  This can be useful if you wish to only send registration data when some condition has changed.
  37 On large collectives, registration messages can be quite high-volume. It's worthwhile to sample the size of your
  38 registration messages and multiply by the number of nodes to determine an appropriate frequency to send them.
  39
  40 To configure it to be used you just need the following in your config:
  41
  42 {% highlight ini %}
  43 registerinterval = 300
  44 registration = Agentlist
  45
  46 # only valid since 1.3.0 and newer
  47 registration_collective = development
  48 {% endhighlight %}
  49
  50 This will cause the plugin to be called every 300 seconds to the development collective, if you do not configure
  51 a target collective explicitely it will target the main collective for the given node.
  52
  53 We do not provide the receiving end of this in the core mcollective. You will need to write an agent called
  54 *registration* and do something useful with the data you receive from all the nodes. You can find
  55 [a simple monitoring system][RegistrationMonitor] built using this method as an example. The receiving agent
  56 can simply be installed as an extra mcollectived plugin on a node which participates in the collective.
  57
  58 You need to note a few things about the receiving agents:
  59
  60  * They need to be fast. You'll receive a lot of registration messages so if your agent talks to a database that
  61    is slow you'll run into problems
  62  * They should not return anything other than *nil*. The MCollective server will interpret *nil* from an agent as
  63    an indication that you do not want to send back any reply.  Replying to registration requests is almost always undesired.
  64
  65 There's nothing preventing you from running more than one type of receiving agent in your collective, you can have one
  66 on your monitor server as above and another with completely different code on a web server feeding a local
  67 cache for your web interfaces.  As long as both agents are called *registration* you'll be fine. However this
  68 does mean you can't run more than one registration receiver on the same server.