website/reference/ui/filters.md

   1 ---
   2 layout: default
   3 title: Discovery Filters
   4 ---
   5
   6 [FactPlugin]: /mcollective/reference/plugins/facts.html
   7
   8 Using filters to control discovery and addressing is a key concept in mcollective.
   9 You can use facts, classes, agents and server identities in filters and combine
  10 to narrow down what hosts you will affect.
  11
  12 To determine if your client support filters use the _--help_ option:
  13
  14
  15 {% highlight console %}
  16 $ mco rpc --help
  17 .
  18 .
  19 .
  20 Host Filters
  21     -W, --with FILTER                Combined classes and facts filter
  22     -F, --wf, --with-fact fact=val   Match hosts with a certain fact
  23     -C, --wc, --with-class CLASS     Match hosts with a certain config management class
  24     -A, --wa, --with-agent AGENT     Match hosts with a certain agent
  25     -I, --wi, --with-identity IDENT  Match hosts with a certain configured identity
  26 {% endhighlight %}
  27
  28 If you see a section as above then the client supports filters, this is the default
  29 for all clients using SimpleRPC.
  30
  31 All filters support Regular Expressions and some support comparisons like greater than
  32 or less than.
  33
  34 Filters are applied in a combined manner, if you supply 5 filters they must all match
  35 your nodes.
  36
  37 ## Fact Filters
  38
  39 Filtering on facts require that you've correctly set up a [FactPlugin].  The examples below
  40 show common fact filters.
  41
  42 Install the ZSH package on machines with the fact _country=de_:
  43
  44 {% highlight console %}
  45 % mco rpc package install zsh -F country=de
  46 {% endhighlight %}
  47
  48 Install the ZSH package on machines where the _country_ fact starts with the letter _d_:
  49
  50 {% highlight console %}
  51 % mco rpc package install zsh -F country=/^d/
  52 {% endhighlight %}
  53
  54 {% highlight console %}
  55 % mco rpc package install zsh -F country=~^d
  56 {% endhighlight %}
  57
  58 Install the ZSH package on machines with more than 2 CPUs, other available operators
  59 include _==, &lt;=, &gt;=, &lt;, &gt;, !=_.  For facts where the comparison and the
  60 actual fact is numeric it will do a numerical comparison else it wil do alphabetical:
  61
  62 {% highlight console %}
  63 % mco rpc package install zsh -F "physicalprocessorcount>=2"
  64 {% endhighlight %}
  65
  66 ## Agent, Identity and Class filters
  67
  68 These filters all work on the same basic pattern, they just support equality or regular
  69 expressions:
  70
  71 Install ZSH on machines with hostnames starting with _web_:
  72
  73 {% highlight console %}
  74 % mco rpc package install zsh -I /^web/
  75 {% endhighlight %}
  76
  77 Install ZSH on machines with hostnames _web1.example.com_:
  78
  79 {% highlight console %}
  80 % mco rpc package install zsh -I web1.example.com
  81 {% endhighlight %}
  82
  83 ## Combining Fact and Class filters
  84
  85 As a short-hand you can combine Fact and Class filters into a single filter:
  86
  87 Install ZSH on machines in Germany that has classes matching _/apache/_:
  88
  89 {% highlight console %}
  90 % mco rpc package install zsh -W "/apache/ country=de"
  91 {% endhighlight %}
  92