--- /dev/null
+---
+layout: default
+title: Registration
+toc: false
+---
+[RegistrationMonitor]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/AgentRegistrationMonitor
+
+MCollective supports the ability for each node to register with a central inventory. The core functionality
+of Mcollective doesn't require registration internally; it's simply provided as a framework to enable you to
+build inventory systems or Web UIs.
+
+## Details
+
+Registration plugins are easy to write. You can configure your nodes to use your own or the provided one.
+
+The one we provide simply sends a list of agents to the inventory. It's available in the plugins directory
+under *registration/agentlist.rb* and can be seen in its entirety below:
+
+{% highlight ruby %}
+module MCollective
+ module Registration
+ # A registration plugin that simply sends in the list of agents we have
+ class Agentlist<Base
+ def body
+ MCollective::Agents.agentlist
+ end
+ end
+ end
+end
+{% endhighlight %}
+
+You can see it's very simple, you just need to subclass *MCollective::Registration::Base* to ensure they get
+loaded into the plugin system and provide a _body_ method whose return value will be sent to the registration agent(s).
+
+The registration plugin can decide if a message should be sent or not. If your plugin responds with a _nil_ value the
+message will not be sent. This can be useful if you wish to only send registration data when some condition has changed.
+On large collectives, registration messages can be quite high-volume. It's worthwhile to sample the size of your
+registration messages and multiply by the number of nodes to determine an appropriate frequency to send them.
+
+To configure it to be used you just need the following in your config:
+
+{% highlight ini %}
+registerinterval = 300
+registration = Agentlist
+
+# only valid since 1.3.0 and newer
+registration_collective = development
+{% endhighlight %}
+
+This will cause the plugin to be called every 300 seconds to the development collective, if you do not configure
+a target collective explicitely it will target the main collective for the given node.
+
+We do not provide the receiving end of this in the core mcollective. You will need to write an agent called
+*registration* and do something useful with the data you receive from all the nodes. You can find
+[a simple monitoring system][RegistrationMonitor] built using this method as an example. The receiving agent
+can simply be installed as an extra mcollectived plugin on a node which participates in the collective.
+
+You need to note a few things about the receiving agents:
+
+ * They need to be fast. You'll receive a lot of registration messages so if your agent talks to a database that
+ is slow you'll run into problems
+ * They should not return anything other than *nil*. The MCollective server will interpret *nil* from an agent as
+ an indication that you do not want to send back any reply. Replying to registration requests is almost always undesired.
+
+There's nothing preventing you from running more than one type of receiving agent in your collective, you can have one
+on your monitor server as above and another with completely different code on a web server feeding a local
+cache for your web interfaces. As long as both agents are called *registration* you'll be fine. However this
+does mean you can't run more than one registration receiver on the same server.
Code Review / packages / precise / mcollective.git / blobdiff