1.. _targeting:
2
3=================
4Targeting Minions
5=================
6
7Targeting minions is specifying which minions should run a command or execute a
8state by matching against hostnames, or system information, or defined groups,
9or even combinations thereof.
10
11For example the command ``salt web1 apache.signal restart`` to restart the
12Apache httpd server specifies the machine ``web1`` as the target and the
13command will only be run on that one minion.
14
15Similarly when using States, the following :term:`top file <Top File>` specifies that only
16the ``web1`` minion should execute the contents of ``webserver.sls``:
17
18.. code-block:: yaml
19
20    base:
21      'web1':
22        - webserver
23
24The simple target specifications, glob, regex, and list will cover many use
25cases, and for some will cover all use cases, but more powerful options exist.
26
27Targeting with Grains
28=====================
29
30The Grains interface was built into Salt to allow minions to be targeted by
31system properties. So minions running on a particular operating system can
32be called to execute a function, or a specific kernel.
33
34Calling via a grain is done by passing the -G option to salt, specifying
35a grain and a glob expression to match the value of the grain. The syntax for
36the target is the grain key followed by a glob expression: "os:Arch*".
37
38.. code-block:: bash
39
40    salt -G 'os:Fedora' test.version
41
42Will return True from all of the minions running Fedora.
43
44To discover what grains are available and what the values are, execute the
45grains.item salt function:
46
47.. code-block:: bash
48
49    salt '*' grains.items
50
51More info on using targeting with grains can be found :ref:`here
52<targeting-grains>`.
53
54Compound Targeting
55==================
56
57.. versionadded:: 0.9.5
58
59Multiple target interfaces can be used in conjunction to determine the command
60targets. These targets can then be combined using ``and`` or ``or`` statements.
61This is well defined with an example:
62
63.. code-block:: bash
64
65    salt -C 'G@os:Debian and webser* or E@db.*' test.version
66
67In this example any minion who's id starts with ``webser`` and is running
68Debian, or any minion who's id starts with db will be matched.
69
70The type of matcher defaults to glob, but can be specified with the
71corresponding letter followed by the ``@`` symbol. In the above example a grain
72is used with ``G@`` as well as a regular expression with ``E@``. The
73``webser*`` target does not need to be prefaced with a target type specifier
74because it is a glob.
75
76More info on using compound targeting can be found :ref:`here
77<targeting-compound>`.
78
79Node Group Targeting
80====================
81
82.. versionadded:: 0.9.5
83
84For certain cases, it can be convenient to have a predefined group of minions
85on which to execute commands. This can be accomplished using what are called
86:ref:`nodegroups <targeting-nodegroups>`. Nodegroups allow for predefined
87compound targets to be declared in the master configuration file, as a sort of
88shorthand for having to type out complicated compound expressions.
89
90.. code-block:: yaml
91
92    nodegroups:
93      group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com'
94      group2: 'G@os:Debian and foo.domain.com'
95      group3: 'G@os:Debian and N@group1'
96
97
98Advanced Targeting Methods
99==========================
100
101There are many ways to target individual minions or groups of minions in Salt:
102
103.. toctree::
104    :maxdepth: 2
105
106    globbing
107    grains
108    pillar
109    ipcidr
110    compound
111    nodegroups
112    batch
113    range
114
115
116Loadable Matchers
117=================
118
119.. versionadded:: 2019.2.0
120
121Internally targeting is implemented with chunks of code called Matchers.  As of
122the 2019.2.0 release, matchers can be loaded dynamically.  Currently new matchers
123cannot be created, but existing matchers can have their functionality altered or
124extended.  For more information on Matchers see
125
126.. toctree::
127    :maxdepth: 2
128
129    Loadable Matchers <../matchers/index.rst>
130