Matchers

New 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