1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Understanding Macros and How They Work</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<meta name="keywords" content="Supervision, Icinga, Nagios, Linux">
<link rel="home" href="index.html" title="Icinga Version 1.0.2 Documentation">
<link rel="up" href="ch05.html" title="Chapter 5. The Basics">
<link rel="prev" href="plugins.html" title="Icinga Plugins">
<link rel="next" href="macrolist.html" title="Standard Macros in Icinga">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<CENTER><IMG src="../images/logofullsize.png" border="0" alt="Icinga" title="Icinga"></CENTER>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Understanding Macros and How They Work</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="plugins.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. The Basics</th>
<td width="20%" align="right"> <a accesskey="n" href="macrolist.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section" title="Understanding Macros and How They Work">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="macros"></a><a name="macro_overview"></a>Understanding Macros and How They Work</h2></div></div></div>
<p><span class="bold"><strong>Macros</strong></span></p>
<p>One of the main features that make Icinga so flexible is the ability to use macros in command definitions. Macros
allow you to reference information from hosts, services, and other sources in your commands.</p>
<p><span class="bold"><strong>Macro Substitution - How Macros Work</strong></span></p>
<p>Before Icinga executes a command, it will replace any macros it finds in the command definition with their
corresponding values. This macro substitution occurs for all types of commands that Icinga executes - host and service
checks, notifications, event handlers, etc.</p>
<p>Certain macros may themselves contain other macros. These include the $HOSTNOTES$, $HOSTNOTESURL$, $HOSTACTIONURL$,
$SERVICENOTES$, $SERVICENOTESURL$, and $SERVICEACTIONURL$ macros.</p>
<p><span class="bold"><strong>Example 1: Host Address Macro</strong></span></p>
<p>When you use host and service macros in command definitions, they refer to values for the host or service for which the
command is being run. Let's try an example. Assuming we are using a host definition and a <span class="emphasis"><em>check_ping</em></span>
command defined like this:</p>
<pre class="screen"> define host{
host_name linuxbox
address 192.168.1.2
check_command check_ping
...
}
define command{
command_name check_ping
command_line /usr/local/icinga/libexec/check_ping -H $HOSTADDRESS$ -w 100.0,90% -c 200.0,60%
}</pre>
<p>the expanded/final command line to be executed for the host's check command would look like this:</p>
<pre class="screen"># /usr/local/icinga/libexec/check_ping -H 192.168.1.2 -w 100.0,90% -c 200.0,60%</pre>
<p>Pretty simple, right? The beauty in this is that you can use a single command definition to check an unlimited number of
hosts. Each host can be checked with the same command definition because each host's address is automatically substituted in the
command line before execution.</p>
<p><span class="bold"><strong>Example 2: Command Argument Macros</strong></span></p>
<p>You can pass arguments to commands as well, which is quite handy if you'd like to keep your command definitions rather
generic. Arguments are specified in the object (i.e. host or service) definition, by separating them from the command name with
exclamation marks (!) like so:</p>
<pre class="screen"> define service{
host_name linuxbox
service_description PING
check_command check_ping!200.0,80%!400.0,40%
...
}</pre>
<p>In the example above, the service check command has two arguments (which can be referenced with <a class="link" href="macrolist.html#macrolist-arg">$ARGn$</a> macros). The $ARG1$ macro will be "<span class="color">200.0,80%</span>" and $ARG2$ will be "<span class="color">400.0,40%</span>" (both
without quotes). Assuming we are using the host definition given earlier and a <span class="emphasis"><em>check_ping</em></span> command defined
like this:</p>
<pre class="screen"> define command{
command_name check_ping
command_line /usr/local/icinga/libexec/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$
}</pre>
<p>the expanded/final command line to be executed for the service's check command would look like this:</p>
<pre class="screen"># /usr/local/icinga/libexec/check_ping -H 192.168.1.2 -w 200.0,80% -c 400.0,40%</pre>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
<p>If you need to pass bang (!) characters in your command arguments, you can do so by escaping them with a backslash (\).
If you need to include backslashes in your command arguments, they should also be escaped with a backslash.</p>
</td></tr>
</table></div>
<p><span class="bold"><strong>On-Demand Macros</strong></span></p>
<p>Normally when you use host and service macros in command definitions, they refer to values for the host or service for
which the command is being run. For instance, if a host check command is being executed for a host named "linuxbox", all the
<a class="link" href="macrolist.html" title="Standard Macros in Icinga">standard host macros</a> will refer to values for that host ("linuxbox").</p>
<p>If you would like to reference values for another host or service in a command (for which the command is not being run),
you can use what are called "on-demand" macros. On-demand macros look like normal macros, except for the fact that they contain
an identifier for the host or service from which they should get their value. Here's the basic format for on-demand
macros:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>$<span class="emphasis"><em>HOSTMACRONAME</em></span>:<span class="emphasis"><em>host_name</em></span>$</p>
</li>
<li class="listitem">
<p>$<span class="emphasis"><em>SERVICEMACRONAME</em></span>:<span class="emphasis"><em>host_name</em></span>:<span class="emphasis"><em>service_description</em></span>$</p>
</li>
</ul></div>
<p>Replace <span class="emphasis"><em>HOSTMACRONAME</em></span> and <span class="emphasis"><em>SERVICEMACRONAME</em></span> with the name of one of the standard
host of service macros found <a class="link" href="macrolist.html" title="Standard Macros in Icinga">here</a>.</p>
<p>Note that the macro name is separated from the host or service identifier by a colon (:). For on-demand service macros,
the service identifier consists of both a host name and a service description - these are separated by a colon (:) as
well.</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
<p>On-demand service macros can contain an empty host name field. In this case the name of the host associated with the
service will automatically be used.</p>
</td></tr>
</table></div>
<p>Examples of on-demand host and service macros follow:</p>
<pre class="screen"> $HOSTDOWNTIME:myhost$ <--- On-demand host macro
$SERVICESTATEID:novellserver:DS Database$ <--- On-demand service macro
$SERVICESTATEID::CPU Load$ <--- On-demand service macro with blank host name field</pre>
<p>On-demand macros are also available for hostgroup, servicegroup, contact, and contactgroup macros. For example:</p>
<pre class="screen"> $CONTACTEMAIL:john$ <--- On-demand contact macro
$CONTACTGROUPMEMBERS:linux-admins$ <--- On-demand contactgroup macro
$HOSTGROUPALIAS:linux-servers$ <--- On-demand hostgroup macro
$SERVICEGROUPALIAS:DNS-Cluster$ <--- On-demand servicegroup macro</pre>
<p><span class="bold"><strong>On-Demand Group Macros</strong></span></p>
<p>You can obtain the values of a macro across all contacts, hosts, or services in a specific group by using a special format
for your on-demand macro declaration. You do this by referencing a specific host group, service group, or contact group name in
an on-demand macro, like so:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>$<span class="emphasis"><em>HOSTMACRONAME</em></span>:<span class="emphasis"><em>hostgroup_name</em></span>:<span class="emphasis"><em>delimiter</em></span>$</p>
</li>
<li class="listitem">
<p>$<span class="emphasis"><em>SERVICEMACRONAME</em></span>:<span class="emphasis"><em>servicegroup_name</em></span>:<span class="emphasis"><em>delimiter</em></span>$</p>
</li>
<li class="listitem">
<p>$<span class="emphasis"><em>CONTACTMACRONAME</em></span>:<span class="emphasis"><em>contactgroup_name</em></span>:<span class="emphasis"><em>delimiter</em></span>$</p>
</li>
</ul></div>
<p>Replace <span class="emphasis"><em>HOSTMACRONAME</em></span>, <span class="emphasis"><em>SERVICEMACRONAME</em></span>, and
<span class="emphasis"><em>CONTACTMACRONAME</em></span> with the name of one of the standard host, service, or contact macros found <a class="link" href="macrolist.html" title="Standard Macros in Icinga">here</a>. The delimiter you specify is used to separate macro values for each group member.</p>
<p>For example, the following macro will return a comma-separated list of host state ids for hosts that are members of the
<span class="emphasis"><em>hg1</em></span> hostgroup:</p>
<pre class="screen"> $HOSTSTATEID:hg1:,$</pre>
<p>This macro definition will return something that looks like this:</p>
<pre class="screen"> 0,2,1,1,0,0,2</pre>
<p><span class="bold"><strong>Custom Variable Macros</strong></span></p>
<p>Any <a class="link" href="customobjectvars.html" title="Custom Object Variables">custom object variables</a> that you define in host, service, or contact
definitions are also available as macros. Custom variable macros are named as follows:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>$_HOST<span class="emphasis"><em>varname</em></span>$</p>
</li>
<li class="listitem">
<p>$_SERVICE<span class="emphasis"><em>varname</em></span>$</p>
</li>
<li class="listitem">
<p>$_CONTACT<span class="emphasis"><em>varname</em></span>$</p>
</li>
</ul></div>
<p>Take the following host definition with a custom variable called "_MACADDRESS"...</p>
<pre class="screen"> define host{
host_name linuxbox
address 192.168.1.1
_MACADDRESS 00:01:02:03:04:05
...
}</pre>
<p>The _MACADDRESS custom variable would be available in a macro called <span class="color">$_HOSTMACADDRESS$</span>. More information on custom object variables and how they can be used in macros can be
found <a class="link" href="customobjectvars.html" title="Custom Object Variables">here</a>.</p>
<p><span class="bold"><strong>Macro Cleansing</strong></span></p>
<p>Some macros are stripped of potentially dangerous shell metacharacters before being substituted into commands to be
executed. Which characters are stripped from the macros depends on the setting of the <a class="link" href="configmain.html#configmain-illegal_macro_output_chars">illegal_macro_output_chars</a> directive. The following macros are stripped
of potentially dangerous characters:</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-hostoutput">$HOSTOUTPUT$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-longhostoutput">$LONGHOSTOUTPUT$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-hostperfdata">$HOSTPERFDATA$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-hostackauthor">$HOSTACKAUTHOR$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-hostackcomment">$HOSTACKCOMMENT$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-serviceoutput">$SERVICEOUTPUT$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-longserviceoutput">$LONGSERVICEOUTPUT$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-serviceperfdata">$SERVICEPERFDATA$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-serviceackauthor">$SERVICEACKAUTHOR$</a></p>
</li>
<li class="listitem">
<p><a class="link" href="macrolist.html#macrolist-serviceackcomment">$SERVICEACKCOMMENT$</a></p>
</li>
</ol></div>
<p><span class="bold"><strong>Macros as Environment Variables</strong></span></p>
<p>Most macros are made available as environment variables for easy reference by scripts or commands that are executed by
Icinga. For purposes of security and sanity, <a class="link" href="macrolist.html#macrolist-user">$USERn$</a> and "on-demand" host and
service macros are <span class="underline">not</span> made available as environment variables.</p>
<p>Environment variables that contain standard macros are named the same as their corresponding macro names (listed <a class="link" href="macrolist.html" title="Standard Macros in Icinga">here</a>), with "NAGIOS_" prepended to their names. For example, the <a class="link" href="macrolist.html#macrolist-hostname">$HOSTNAME$</a> macro would be available as an environment variable named
"NAGIOS_HOSTNAME".</p>
<p><span class="bold"><strong>Available Macros</strong></span></p>
<p>A list of all the macros that are available in Icinga, as well as a chart of when they can be used, can be found
<a class="link" href="macrolist.html" title="Standard Macros in Icinga">here</a>.</p>
<a class="indexterm" name="id1964968"></a>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="plugins.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="macrolist.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Icinga Plugins </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Standard Macros in Icinga</td>
</tr>
</table>
</div>
<P class="copyright">© 2009-2010 Icinga Development Team, http://www.icinga.org</P>
</body>
</html>
|
