1.. _matchers:
2
3========
4Matchers
5========
6
7.. versionadded:: 3000
8
9Matchers are modules that provide Salt's targeting abilities.  As of the
103000 release, matchers can be dynamically loaded.  Currently new matchers
11cannot be created because the required plumbing for the CLI does not exist yet.
12Existing matchers may have their functionality altered or extended.
13
14For details of targeting methods, see the :ref:`Targeting <targeting>` topic.
15
16A matcher module must have a function called ``match()``. This function ends up
17becoming a method on the Matcher class.  All matcher functions require at least
18two arguments, ``self`` (because the function will be turned into a method), and
19``tgt``, which is the actual target string.  The grains and pillar matchers also
20take a ``delimiter`` argument and should default to ``DEFAULT_TARGET_DELIM``.
21
22Like other Salt loadable modules, modules that override built-in functionality
23can be placed in ``file_roots`` in a special directory and then copied to the
24minion through the normal sync process.  :py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
25will transfer all loadable modules, and the 3000 release introduces
26:py:func:`saltutil.sync_matchers <salt.modules.saltutil.sync_matchers>`.  For matchers, the directory is
27``/srv/salt/_matchers`` (assuming your ``file_roots`` is set to the default
28``/srv/salt``).
29
30As an example, let's modify the ``list`` matcher to have the separator be a
31'``/``' instead of the default '``,``'.
32
33
34.. code-block:: python
35
36    from __future__ import absolute_import, print_function, unicode_literals
37    from salt.ext import six  # pylint: disable=3rd-party-module-not-gated
38
39
40    def match(self, tgt):
41        """
42        Determines if this host is on the list
43        """
44        if isinstance(tgt, six.string_types):
45            # The stock matcher splits on `,`.  Change to `/` below.
46            tgt = tgt.split("/")
47        return bool(self.opts["id"] in tgt)
48
49
50Place this code in a file called ``list_matcher.py`` in ``_matchers`` in your
51``file_roots``. Sync this down to your minions with
52:py:func:`saltutil.sync_matchers <salt.modules.saltutil.sync_matchers>`.
53Then attempt to match with the following, replacing ``minionX`` with three of your minions.
54
55.. code-block:: shell
56
57   salt -L 'minion1/minion2/minion3' test.ping
58
59
60Three of your minions should respond.
61
62The current supported matchers and associated filenames are
63
64===============  ======================  ===================
65Salt CLI Switch  Match Type              Filename
66===============  ======================  ===================
67<none>           Glob                    glob_match.py
68-C               Compound                compound_match.py
69-E               Perl-Compatible         pcre_match.py
70                 Regular Expressions
71-L               List                    list_match.py
72-G               Grain                   grain_match.py
73-P               Grain Perl-Compatible   grain_pcre_match.py
74                 Regular Expressions
75-N               Nodegroup               nodegroup_match.py
76-R               Range                   range_match.py
77-I               Pillar                  pillar_match.py
78-J               Pillar Perl-Compatible  pillar_pcre.py
79                 Regular Expressions
80-S               IP-Classless Internet   ipcidr_match.py
81                 Domain Routing
82===============  ======================  ===================
83