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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Passive Host and Service Checks</title>
<STYLE type="text/css">
<!--
.Default { font-family: verdana,arial,serif; font-size: 8pt; }
.PageTitle { font-family: verdana,arial,serif; font-size: 12pt; font-weight: bold; }
-->
</STYLE>
</head>
<body bgcolor="#FFFFFF" text="black" class="Default">
<p>
<div align="center">
<h2 class="PageTitle">Passive Host and Service Checks</h2>
</div>
</p>
<hr>
<p>
<strong><u>Introduction</u></strong>
</p>
<p>
On of the features of Nagios is that is can process host and service check results that are submitted by external applications. Host and service checks which are performed and submitted to Nagios by external apps are called <i>passive</i> checks. Passive checks can be contrasted with <i>active</i> checks, which are host or service checks that have been initiated by Nagios.
</p>
<p>
<strong><u>Why The Need For Passive Checks?</u></strong>
</p>
<p>
Passive checks are useful for monitoring services that are:
</p>
<p>
<ul>
<li>located behind a firewall, and can therefore not be checked actively from the host running Nagios
<li>asynchronous in nature and can therefore not be actively checked in a reliable manner (e.g. SNMP traps, security alerts, etc.)
</ul>
</p>
<p>
Passive host and service checks are also useful when configured a <a href="distributed.html">distributed monitoring setup</a>.
</p>
<p>
<strong><u>Passive Service Checks vs. Passive Host Checks</u></strong>
</p>
<p>
Passive host and service checks function in a similiar manner, but there are some important limitations in regards to passive host checks. Read <a href="#hostchecks">below</a> for more information about the limitations with passive host checks.
</p>
<p>
<strong><u>How Do Passive Service Checks Work?</u></strong>
</p>
<p>
The only real difference between active and passive checks is that active checks are initiated by Nagios, while passive checks are performed by external applications. Once an external application has performed a service check (either actively or by having received an synchronous event like an SNMP trap or security alert), it submits the results of the service "check" to Nagios through the <a href="configmain.html#command_file">external command file</a>.
</p>
<p>
The next time Nagios processes the contents of the external command file, it will place the results of all passive service 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>
<p>
Nagios will periodically execute a <a href="configmain.html#service_reaper_frequency">service reaper event</a> and scan the service check result queue. Each service check result, regardless of whether the check was active or passive, is processed in the same manner. The service check logic is exactly the same for both types of checks. This provides a seamless method for handling both active and passive service check results.
</p>
<p>
<strong><u>How Do External Apps Submit Service Check Results?</u></strong>
</p>
<p>
External applications can submit service check results to Nagios by writing a PROCESS_SERVICE_CHECK_RESULT <a href="extcommands.html">external command</a> to the <a href="configmain.html#command_file">external command file</a>.
</p>
<p>
The format of the command is as follows:
</p>
<p>
<font color="red"><strong>[<timestamp>] PROCESS_SERVICE_CHECK_RESULT;<host_name>;<description>;<return_code>;<plugin_output></strong></font>
</p>
<p>
where...
</p>
<p>
<ul>
<li><i>timestamp</i> 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.
<li><i>host_name</i> is the short name of the host associated with the service in the service definition
<li><i>description</i> is the description of the service as specified in the service definition
<li><i>return_code</i> is the return code of the check (0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN)
<li><i>plugin_output</i> is the text output of the service check (i.e. the plugin output)
</ul>
</p>
<p>
Note that in order to submit service checks to Nagios, a service must have already been defined in the <a href="configobject.html">object configuration file</a>! Nagios will ignore all check results for services that had not been configured before it was last (re)started.
</p>
<p>
If you only want passive results to be provided for a specific service (i.e. active checks should not be performed), simply set the <i>active_checks_enabled</i> member of the service definition to 0. This will prevent Nagios from ever actively performing a check of the service. Make sure that the <i>passive_checks_enabled</i> member of the service definition is set to 1. If it isn't, Nagios won't process passive checks for the service!
</p>
<p>
An example shell script of how to submit passive service check results to Nagios can be found in the documentation on <a href="volatileservices.html">volatile services</a>.
</p>
<p>
<strong><u>Submitting Passive Service Check Results From Remote Hosts</u></strong>
</p>
<p>
If an application that resides on the same host as Nagios is sending passive 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. In order to allow remote hosts to send passive service check results to the host that runs Nagios, I've developed the <a href="addons.html#nsca">nsca</a> addon. The addon consists of a daemon that runs on the Nagios 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 href="addons.html#nsca">here</a>...
</p>
<p>
<strong><u>Using Both Active And Passive Service Checks</u></strong>
</p>
<p>
Unless you're implementing a <a href="distributed.html">distributed monitoring</a> environment with the central server accepting only passive service checks (and not performing any active checks), you'll probably be using both types of checks in your setup. As mentioned before, active checks are more suited for services that lend themselves to periodic checks (availability of an FTP or web server, etc), whereas passive checks are better off at handling asynchronous events that occur at variable intervals (security alerts, etc.).
</p>
<p>
The image below gives a visual representation of how active and passive service checks can both be used to monitor network resources (click on the image for a larger version).
</p>
<p>
The orange bubbles on the right side of the image are third-party applications that submit passive check results to Nagios' external command file. One of the applications resides on the same host as Nagios, so it can write directly to the command file. The other application resides on a remote host and makes used of the nsca client program and daemon to transfer the passive check results to Nagios.
</p>
<p>
The items on the left side of the image represent active service checks that Nagios is performing. I've shown how the checks can be made for local resources (disk usage, etc.), "exposed" resources on remote hosts (web server, FTP server, etc.), and "private" resources on remote hosts (remote host disk usage, processor load, etc.). In this example, the private resources on the remote hosts are actually checked by making use of the <a href="addons.html#nrpe">nrpe</a> addon, which facilitates the execution of plugins on remote hosts.
</p>
<p>
<a href="images/activepassive.png"><img src="images/activepassive.png" border=1 width=200 height=250></a>
</p>
<a name="hostchecks"></a>
<p>
<strong><u>How Do Passive Host Checks Work?</u></strong>
</p>
<p>
Passive host checks work in a similiar manner to passive service checks. Once an external application has performed a host check, it submits the results of that host "check" to Nagios through the <a href="configmain.html#command_file">external command file</a>. The next time Nagios processes the contents of the external command file, it will process the host check result that was submitted.
</p>
<p>
<strong>WARNING!</strong> Passive host checks have some limitations. Unlike active host checks, Nagios does not attempt to determine whether or host is DOWN or UNREACHABLE with passive checks. Rather, Nagios takes the passive check result to be the actual state the host is in and doesn't try to determine the actual state. In contrast, Nagios attempts to determine the proper status (DOWN or UNREACHABLE) for hosts that are not UP when the host check is active (initiated by Nagios). This can cause problems if you are submitting passive checks from a remote host or you have a <a href="distributed.html">distributed monitoring setup</a> where the parent/child host relationships are different. See the documentation on <a href="networkreachability.html">host reachability</a> for more information on how DOWN and UNREACHABLE states are determined for active host checks.
</p>
<p>
<strong><u>How Do External Apps Submit Host Check Results?</u></strong>
</p>
<p>
External applications can submit host check results to Nagios by writing a PROCESS_HOST_CHECK_RESULT <a href="extcommands.html">external command</a> to the <a href="configmain.html#command_file">external command file</a>.
</p>
<p>
The format of the command is as follows:
</p>
<p>
<font color="red"><strong>[<timestamp>] PROCESS_HOST_CHECK_RESULT;<host_name>;<host_status>;<plugin_output></strong></font>
</p>
<p>
where...
</p>
<p>
<ul>
<li><i>timestamp</i> 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.
<li><i>host_name</i> is the short name of the host (as defined in the host definition)
<li><i>host_status</i> is the status of the host (0=UP, 1=DOWN, 2=UNREACHABLE)
<li><i>plugin_output</i> is the text output of the host check
</ul>
</p>
<p>
Note that in order to submit host checks to Nagios, a host must have already been defined in the <a href="configobject.html">object configuration file</a>! Nagios will ignore all check results for hosts that had not been configured before it was last (re)started.
</p>
<p>
<strong><u>Submitting Passive Host Check Results From Remote Hosts</u></strong>
</p>
<p>
If an application that resides on the same host as Nagios is sending passive 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. In order to allow remote hosts to send passive host check results to the host that runs Nagios, you can use the <a href="addons.html#nsca">nsca</a> addon. The addon consists of a daemon that runs on the Nagios 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 href="addons.html#nsca">here</a>.
</p>
<hr>
</body>
</html>
|
