X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=website%2Freference%2Fplugins%2Fregistration.md;fp=website%2Freference%2Fplugins%2Fregistration.md;h=fc92bc2917269af50b082f1b4c46afc6ff62e573;hb=b87d2f4e68281062df1913440ca5753ae63314a9;hp=0000000000000000000000000000000000000000;hpb=ab0ea530b8ac956091f17b104ab2311336cfc250;p=packages%2Fprecise%2Fmcollective.git

diff --git a/website/reference/plugins/registration.md b/website/reference/plugins/registration.md
new file mode 100644
index 0000000..fc92bc2
--- /dev/null
+++ b/website/reference/plugins/registration.md
@@ -0,0 +1,68 @@
+---
+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.