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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Passive Checks</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="activechecks.html" title="Active Checks">
<link rel="next" href="statetypes.html" title="State Types">
</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">Passive Checks</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="activechecks.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. The Basics</th>
<td width="20%" align="right"> <a accesskey="n" href="statetypes.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section" title="Passive Checks">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="passivechecks"></a><a name="passive_checks"></a>Passive Checks</h2></div></div></div>
<p><span class="bold"><strong>Introduction</strong></span></p>
<p>In most cases you'll use Icinga to monitor your hosts and services using regularly scheduled <a class="link" href="activechecks.html" title="Active Checks">active checks</a>. Active checks can be used to "poll" a device or service for status information
every so often. Icinga also supports a way to monitor hosts and services passively instead of actively. They key features
of passive checks are as follows:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Passive checks are initiated and performed external applications/processes</p>
</li>
<li class="listitem">
<p>Passive check results are submitted to Icinga for processing</p>
</li>
</ul></div>
<p>The major difference between active and passive checks is that active checks are initiated and performed by Icinga,
while passive checks are performed by external applications.</p>
<p><span class="bold"><strong>Uses For Passive Checks</strong></span></p>
<p>Passive checks are useful for monitoring services that are:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Asynchronous in nature and cannot be monitored effectively by polling their status on a regularly scheduled
basis</p>
</li>
<li class="listitem">
<p>Located behind a firewall and cannot be checked actively from the monitoring host</p>
</li>
</ul></div>
<p>Examples of asynchronous services that lend themselves to being monitored passively include SNMP traps and security
alerts. You never know how many (if any) traps or alerts you'll receive in a given time frame, so it's not feasible to just
monitor their status every few minutes.</p>
<p>Passive checks are also used when configuring <a class="link" href="distributed.html" title="Distributed Monitoring">distributed</a> or <a class="link" href="redundancy.html" title="Redundant and Failover Network Monitoring">redundant</a> monitoring installations.</p>
<p><span class="bold"><strong>How Passive Checks Work</strong></span></p>
<p><span class="inlinemediaobject"><img src="../images/passivechecks.png"></span></p>
<p>Here's how passive checks work in more detail...</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p>An external application checks the status of a host or service.</p>
</li>
<li class="listitem">
<p>The external application writes the results of the check to the <a class="link" href="configmain.html#configmain-command_file">external
command file</a>.</p>
</li>
<li class="listitem">
<p>The next time Icinga reads the external command file it will place the results of all passive checks into a
queue for later processing. The same queue that is used for storing results from active checks is also used to store the
results from passive checks.</p>
</li>
<li class="listitem">
<p>Icinga will periodically execute a <a class="link" href="configmain.html#configmain-check_result_reaper_frequency">check result reaper
event</a> and scan the check result queue. Each service check result that is found in the queue is processed in the same
manner - regardless of whether the check was active or passive. Icinga may send out notifications, log alerts, etc.
depending on the check result information.</p>
</li>
</ol></div>
<p>The processing of active and passive check results is essentially identical. This allows for seamless integration of
status information from external applications with Icinga.</p>
<p><span class="bold"><strong>Enabling Passive Checks</strong></span></p>
<p>In order to enable passive checks in Icinga, you'll need to do the following:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Set <a class="link" href="configmain.html#configmain-accept_passive_service_checks">accept_passive_service_checks</a> directive is set to
1.</p>
</li>
<li class="listitem">
<p>Set the <span class="emphasis"><em>passive_checks_enabled</em></span> directive in your host and service definitions is set to 1.</p>
</li>
</ul></div>
<p>If you want to disable processing of passive checks on a global basis, set the <a class="link" href="configmain.html#configmain-accept_passive_service_checks">accept_passive_service_checks</a> directive to 0.</p>
<p>If you would like to disable passive checks for just a few hosts or services, use the
<span class="emphasis"><em>passive_checks_enabled</em></span> directive in the host and/or service definitions to do so.</p>
<p><span class="bold"><strong>Submitting Passive Service Check Results</strong></span></p>
<p>External applications can submit passive service check results to Icinga by writing a PROCESS_SERVICE_CHECK_RESULT
<a class="link" href="extcommands.html" title="External Commands">external command</a> to the external command file.</p>
<p>The format of the command is as follows:</p>
<pre class="screen"> [<timestamp>] PROCESS_SERVICE_CHECK_RESULT;<host_name>;<svc_description>;<return_code>;<plugin_output></pre>
<p>where...</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p><span class="emphasis"><em>timestamp</em></span> is the time in time_t format (seconds since the UNIX epoch) that the service check was
perfomed (or submitted). Please note the single space after the right bracket.</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>host_name</em></span> is the short name of the host associated with the service in the service
definition</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>svc_description</em></span> is the description of the service as specified in the service definition</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>return_code</em></span> is the return code of the check (0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN)</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>plugin_output</em></span> is the text output of the service check (i.e. the plugin output)</p>
</li>
</ul></div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>A service must be defined in Icinga before you can submit passive check results for it! Icinga will ignore
all check results for services that had not been configured before it was last (re)started.</p>
</td></tr>
</table></div>
<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>An example shell script of how to submit passive service check results to Icinga can be found in the
documentation on <a class="link" href="volatileservices.html" title="Volatile Services">volatile services</a>.</p>
</td></tr>
</table></div>
<p><span class="bold"><strong>Submitting Passive Host Check Results</strong></span></p>
<p>External applications can submit passive host check results to Icinga by writing a PROCESS_HOST_CHECK_RESULT
external command to the external command file.</p>
<p>The format of the command is as follows:</p>
<pre class="screen"> [<timestamp>] PROCESS_HOST_CHECK_RESULT;<host_name>;<host_status>;<plugin_output></pre>
<p>where...</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p><span class="emphasis"><em>timestamp</em></span> is the time in time_t format (seconds since the UNIX epoch) that the host check was
perfomed (or submitted). Please note the single space after the right bracket.</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>host_name</em></span> is the short name of the host (as defined in the host definition)</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>host_status</em></span> is the status of the host (0=UP, 1=DOWN, 2=UNREACHABLE)</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>plugin_output</em></span> is the text output of the host check</p>
</li>
</ul></div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>A host must be defined in Icinga before you can submit passive check results for it! Icinga will ignore
all check results for hosts that had not been configured before it was last (re)started.</p>
</td></tr>
</table></div>
<p><span class="bold"><strong>Passive Checks and Host States</strong></span></p>
<p>Unlike with active host checks, Icinga does not (by default) attempt to determine whether or host is DOWN or
UNREACHABLE with passive checks. Rather, Icinga takes the passive check result to be the actual state the host is in and
doesn't try to determine the host's actual state using the <a class="link" href="networkreachability.html" title="Determining Status and Reachability of Network Hosts">reachability logic</a>. This
can cause problems if you are submitting passive checks from a remote host or you have a <a class="link" href="distributed.html" title="Distributed Monitoring">distributed
monitoring setup</a> where the parent/child host relationships are different.</p>
<p>You can tell Icinga to translate DOWN/UNREACHABLE passive check result states to their "proper" state by using the
<a class="link" href="configmain.html#configmain-translate_passive_host_checks">translate_passive_host_checks</a> variable. More information on how
this works can be found <a class="link" href="passivestatetranslation.html" title="Passive Host State Translation">here</a>.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>Passive host checks are normally treated as <a class="link" href="statetypes.html" title="State Types">HARD states</a>, unless the <a class="link" href="configmain.html#configmain-passive_host_checks_are_soft">passive_host_checks_are_soft</a> option is enabled.</p>
</td></tr>
</table></div>
<p><span class="bold"><strong>Submitting Passive Check Results From Remote Hosts</strong></span></p>
<p><span class="inlinemediaobject"><img src="../images/nsca.png"></span></p>
<p>If an application that resides on the same host as Icinga is sending passive host or service check results, it can
simply write the results directly to the external command file as outlined above. However, applications on remote hosts can't do
this so easily.</p>
<p>In order to allow remote hosts to send passive check results to the monitoring host, the <a class="link" href="addons.html#addons-nsca">NSCA</a> addon was developed. The NSCA addon consists of a daemon that runs on the Icinga hosts
and a client that is executed from remote hosts. The daemon will listen for connections from remote clients, perform some basic
validation on the results being submitted, and then write the check results directly into the external command file (as
described above). More information on the NSCA addon can be found <a class="link" href="addons.html#addons-nsca">here</a>.</p>
<a class="indexterm" name="id1984660"></a>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="activechecks.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="statetypes.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Active Checks </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> State Types</td>
</tr>
</table>
</div>
<P class="copyright">© 2009-2010 Icinga Development Team, http://www.icinga.org</P>
</body>
</html>
|
