Updated mcollective.init according to OSCI-658

[packages/precise/mcollective.git] / website / reference / ui / filters.md

diff --git a/website/reference/ui/filters.md b/website/reference/ui/filters.md
new file mode 100644 (file)
index 0000000..396c64a
--- /dev/null
+++ b/website/reference/ui/filters.md
@@ -0,0 +1,92 @@
+---
+layout: default
+title: Discovery Filters
+---
+
+[FactPlugin]: /mcollective/reference/plugins/facts.html
+
+Using filters to control discovery and addressing is a key concept in mcollective.
+You can use facts, classes, agents and server identities in filters and combine
+to narrow down what hosts you will affect.
+
+To determine if your client support filters use the _--help_ option:
+
+
+{% highlight console %}
+$ mco rpc --help
+.
+.
+.
+Host Filters
+    -W, --with FILTER                Combined classes and facts filter
+    -F, --wf, --with-fact fact=val   Match hosts with a certain fact
+    -C, --wc, --with-class CLASS     Match hosts with a certain config management class
+    -A, --wa, --with-agent AGENT     Match hosts with a certain agent
+    -I, --wi, --with-identity IDENT  Match hosts with a certain configured identity
+{% endhighlight %}
+
+If you see a section as above then the client supports filters, this is the default
+for all clients using SimpleRPC.
+
+All filters support Regular Expressions and some support comparisons like greater than
+or less than.
+
+Filters are applied in a combined manner, if you supply 5 filters they must all match
+your nodes.
+
+## Fact Filters
+
+Filtering on facts require that you've correctly set up a [FactPlugin].  The examples below
+show common fact filters.
+
+Install the ZSH package on machines with the fact _country=de_:
+
+{% highlight console %}
+% mco rpc package install zsh -F country=de
+{% endhighlight %}
+
+Install the ZSH package on machines where the _country_ fact starts with the letter _d_:
+
+{% highlight console %}
+% mco rpc package install zsh -F country=/^d/
+{% endhighlight %}
+
+{% highlight console %}
+% mco rpc package install zsh -F country=~^d
+{% endhighlight %}
+
+Install the ZSH package on machines with more than 2 CPUs, other available operators
+include _==, <=, >=, <, >, !=_.  For facts where the comparison and the
+actual fact is numeric it will do a numerical comparison else it wil do alphabetical:
+
+{% highlight console %}
+% mco rpc package install zsh -F "physicalprocessorcount>=2"
+{% endhighlight %}
+
+## Agent, Identity and Class filters
+
+These filters all work on the same basic pattern, they just support equality or regular
+expressions:
+
+Install ZSH on machines with hostnames starting with _web_:
+
+{% highlight console %}
+% mco rpc package install zsh -I /^web/
+{% endhighlight %}
+
+Install ZSH on machines with hostnames _web1.example.com_:
+
+{% highlight console %}
+% mco rpc package install zsh -I web1.example.com
+{% endhighlight %}
+
+## Combining Fact and Class filters
+
+As a short-hand you can combine Fact and Class filters into a single filter:
+
+Install ZSH on machines in Germany that has classes matching _/apache/_:
+
+{% highlight console %}
+% mco rpc package install zsh -W "/apache/ country=de"
+{% endhighlight %}
+