index.rst

Matchers

.. versionadded:: Neon

Matchers are modules that provide Salt's targeting abilities. As of the Neon 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 Neon 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 ','.

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.

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