.. _matchers:

========
Matchers
========

.. versionadded:: 3000

Matchers are modules that provide Salt's targeting abilities.  As of the
3000 release, matchers can be dynamically loaded.  Currently new matchers
cannot be created because the required plumbing for the CLI does not exist yet.
Existing matchers may have their functionality altered or extended.

For details of targeting methods, see the :ref:`Targeting <targeting>` topic.

A matcher module must have a function called ``match()``. This function ends up
becoming a method on the Matcher class.  All matcher functions require at least
two arguments, ``self`` (because the function will be turned into a method), and
``tgt``, which is the actual target string.  The grains and pillar matchers also
take a ``delimiter`` argument and should default to ``DEFAULT_TARGET_DELIM``.

Like other Salt loadable modules, modules that override built-in functionality
can be placed in ``file_roots`` in a special directory and then copied to the
minion through the normal sync process.  :py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
will transfer all loadable modules, and the 3000 release introduces
:py:func:`saltutil.sync_matchers <salt.modules.saltutil.sync_matchers>`.  For matchers, the directory is
``/srv/salt/_matchers`` (assuming your ``file_roots`` is set to the default
``/srv/salt``).

As an example, let's modify the ``list`` matcher to have the separator be a
'``/``' instead of the default '``,``'.


.. code-block:: python

    from __future__ import absolute_import, print_function, unicode_literals
    from salt.ext import six  # pylint: disable=3rd-party-module-not-gated


    def match(self, tgt):
        """
        Determines if this host is on the list
        """
        if isinstance(tgt, six.string_types):
            # The stock matcher splits on `,`.  Change to `/` below.
            tgt = tgt.split("/")
        return bool(self.opts["id"] in tgt)


Place this code in a file called ``list_matcher.py`` in ``_matchers`` in your
``file_roots``. Sync this down to your minions with
:py:func:`saltutil.sync_matchers <salt.modules.saltutil.sync_matchers>`.
Then attempt to match with the following, replacing ``minionX`` with three of your minions.

.. code-block:: shell

   salt -L 'minion1/minion2/minion3' test.ping


Three of your minions should respond.

The current supported matchers and associated filenames are

===============  ======================  ===================
Salt CLI Switch  Match Type              Filename
===============  ======================  ===================
<none>           Glob                    glob_match.py
-C               Compound                compound_match.py
-E               Perl-Compatible         pcre_match.py
                 Regular Expressions
-L               List                    list_match.py
-G               Grain                   grain_match.py
-P               Grain Perl-Compatible   grain_pcre_match.py
                 Regular Expressions
-N               Nodegroup               nodegroup_match.py
-R               Range                   range_match.py
-I               Pillar                  pillar_match.py
-J               Pillar Perl-Compatible  pillar_pcre.py
                 Regular Expressions
-S               IP-Classless Internet   ipcidr_match.py
                 Domain Routing
===============  ======================  ===================