# Matchers

Added in version 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 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. `saltutil.sync_all` will transfer all loadable modules, and the 3000 release introduces `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 '`,`'.

    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_match.py` in a `_matchers` directory in your `file_roots`. Sync this down to your minions with `saltutil.sync_matchers`. Then attempt to match with the following, replacing `minionX` with three of your minions.

    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 Regular Expressions | pcre_match.py
-L | List | list_match.py
-G | Grain | grain_match.py
-P | Grain Perl-Compatible Regular Expressions | grain_pcre_match.py
-N | Nodegroup | nodegroup_match.py
-R | Range | range_match.py
-I | Pillar | pillar_match.py
-J | Pillar Perl-Compatible Regular Expressions | pillar_pcre.py
-S | IP-Classless Internet Domain Routing | ipcidr_match.py