website/reference/plugins/facts.md

   1 ---
   2 layout: default
   3 title: Writing Fact Plugins
   4 toc: false
   5 ---
   6 [SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
   7 [Registration]: registration.html
   8
   9 Fact plugins are used during discovery whenever you run the agent with queries like *-W country=de*.
  10
  11 The default setup uses a YAML file typically stored in */etc/mcollective/facts.yaml* to read facts.  There are however many fact systems like Reductive Labs Facter and Opscode Ohai or you can come up with your own.  The facts plugin type lets you write code to access these tools.
  12
  13 Facts at the moment should be simple *variable = value* style flat Hashes, if you have a hierarchical fact system like Ohai you can flatten them into *var.subvar = value* style variables.
  14
  15 ## Details
  16 Implementing a facts plugin is made simple by inheriting from *MCollective::Facts::Base*, in that case you just need to provide 1 method, the YAML plugin code can be seen below:
  17
  18 For releases in the 1.0.x release cycle and older, use this plugin format:
  19
  20 {% highlight ruby linenos %}
  21 module MCollective
  22     module Facts
  23         require 'yaml'
  24
  25         # A factsource that reads a hash of facts from a YAML file
  26         class Yaml<Base
  27             def self.get_facts
  28                 config = MCollective::Config.instance
  29
  30                 facts = {}
  31
  32                 YAML.load_file(config.pluginconf["yaml"]).each_pair do |k, v|
  33                     facts[k] = v.to_s
  34                 end
  35
  36                 facts
  37             end
  38         end
  39     end
  40 end
  41 {% endhighlight %}
  42
  43 For releases 1.1.x and onward use this format:
  44
  45 {% highlight ruby linenos %}
  46 module MCollective
  47     module Facts
  48         require 'yaml'
  49
  50         class Yaml_facts<Base
  51             def load_facts_from_source
  52                 config = MCollective::Config.instance
  53
  54                 facts = {}
  55
  56                 YAML.load_file(config.pluginconf["yaml"]).each_pair do |k, v|
  57                     facts[k] = v.to_s
  58                 end
  59
  60                 facts
  61             end
  62         end
  63     end
  64 end
  65 {% endhighlight %}
  66
  67 If using the newer format in newer releases of mcollective you do not need to worry about caching or
  68 thread safety as the base class does this for you.  You can force reloading of facts by creating a
  69 *force_reload?* method that should return *true* or *false*.  Returning *true* will force the cache
  70 to be rebuilt.
  71
  72 You can see that all you have to do is provide *self.get_facts* which should return a Hash as described above.
  73
  74 There's a sample using Puppet Labs Facter on the plugins project if you wish to see an example that queries an external fact source.
  75
  76 Once you've written your plugin you can save it in the plugins directory and configure mcollective to use it:
  77
  78 {% highlight ini %}
  79 factsource = yaml
  80 {% endhighlight %}
  81
  82 This will result in *MCollective::Facts::Yaml* or *MCollective::Facts::Yaml_facts* being used as source for your facts.