1 # <a id="agent-based-checks-addon"></a> Additional Agent-based Checks
3 If the remote services are not directly accessible through the network, a
4 local agent installation exposing the results to check queries can
7 ## <a id="agent-based-checks-snmp"></a> SNMP
9 The SNMP daemon runs on the remote system and answers SNMP queries by plugin
10 binaries. The [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins) ships
11 the `check_snmp` plugin binary, but there are plenty of [existing plugins](14-addons-plugins.md#plugins)
12 for specific use cases already around, for example monitoring Cisco routers.
14 The following example uses the [SNMP ITL](7-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just
15 overrides the `snmp_oid` custom attribute. A service is created for all hosts which
16 have the `snmp-community` custom attribute.
18 apply Service "uptime" {
19 import "generic-service"
21 check_command = "snmp"
22 vars.snmp_oid = "1.3.6.1.2.1.1.3.0"
23 vars.snmp_miblist = "DISMAN-EVENT-MIB"
25 assign where host.vars.snmp_community != ""
28 Additional SNMP plugins are available using the [Manubulon SNMP Plugins](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
30 If no `snmp_miblist` is specified, the plugin will default to `ALL`. As the number of available MIB files
31 on the system increases so will the load generated by this plugin if no `MIB` is specified.
32 As such, it is recommended to always specify at least one `MIB`.
34 ## <a id="agent-based-checks-ssh"></a> SSH
36 Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching
37 its return code and output. The `by_ssh` command object is part of the built-in templates and
38 requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins).
40 object CheckCommand "by_ssh_swap" {
43 vars.by_ssh_command = "/usr/lib/nagios/plugins/check_swap -w $by_ssh_swap_warn$ -c $by_ssh_swap_crit$"
44 vars.by_ssh_swap_warn = "75%"
45 vars.by_ssh_swap_crit = "50%"
48 object Service "swap" {
49 import "generic-service"
51 host_name = "remote-ssh-host"
53 check_command = "by_ssh_swap"
55 vars.by_ssh_logname = "icinga"
58 ## <a id="agent-based-checks-nrpe"></a> NRPE
60 [NRPE](http://docs.icinga.org/latest/en/nrpe.html) runs as daemon on the remote client including
61 the required plugins and command definitions.
62 Icinga 2 calls the `check_nrpe` plugin binary in order to query the configured command on the
67 > The NRPE protocol is considered insecure and has multiple flaws in its
68 > design. Upstream is not willing to fix these issues.
70 > In order to stay safe, please use the native [Icinga 2 client](11-icinga2-client.md#icinga2-client)
73 The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
74 can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
76 You can use the `check_nrpe` plugin from the NRPE project to query the NRPE daemon.
77 Icinga 2 provides the [nrpe check command](7-icinga-template-library.md#plugin-check-command-nrpe) for this:
81 object Service "users" {
82 import "generic-service"
84 host_name = "remote-nrpe-host"
86 check_command = "nrpe"
87 vars.nrpe_command = "check_users"
92 command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
94 If you are planning to pass arguments to NRPE using the `-a`
95 command line parameter, make sure that your NRPE daemon has them
96 supported and enabled.
100 > Enabling command arguments in NRPE is considered harmful
101 > and exposes a security risk allowing attackers to execute
102 > commands remotely. Details at [seclists.org](http://seclists.org/fulldisclosure/2014/Apr/240).
104 The plugin check command `nrpe` provides the `nrpe_arguments` custom
105 attribute which expects either a single value or an array of values.
109 object Service "nrpe-disk-/" {
110 import "generic-service"
112 host_name = "remote-nrpe-host"
114 check_command = "nrpe"
115 vars.nrpe_command = "check_disk"
116 vars.nrpe_arguments = [ "20%", "10%", "/" ]
119 Icinga 2 will execute the nrpe plugin like this:
121 /usr/lib/nagios/plugins/check_nrpe -H <remote-nrpe-host> -c 'check_disk' -a '20%' '10%' '/'
123 NRPE expects all additional arguments in an ordered fashion
124 and interprets the first value as `$ARG1$` macro, the second
125 value as `$ARG2$`, and so on.
129 command[check_disk]=/usr/local/icinga/libexec/check_disk -w $ARG1$ -c $ARG2$ -p $ARG3$
131 Using the above example with `nrpe_arguments` the command
132 executed by the NRPE daemon looks similar to that:
134 /usr/local/icinga/libexec/check_disk -w 20% -c 10% -p /
136 You can pass arguments in a similar manner to [NSClient++](12-agent-based-checks.md#agent-based-checks-nsclient)
137 when using its NRPE supported check method.
139 ## <a id="agent-based-checks-nsclient"></a> NSClient++
141 [NSClient++](http://nsclient.org) works on both Windows and Linux platforms and is well
142 known for its magnificent Windows support. There are alternatives like the WMI interface,
143 but using `NSClient++` will allow you to run local scripts similar to check plugins fetching
144 the required output and performance counters.
146 You can use the `check_nt` plugin from the Monitoring Plugins project to query NSClient++.
147 Icinga 2 provides the [nscp check command](7-icinga-template-library.md#plugin-check-command-nscp) for this:
151 object Service "disk" {
152 import "generic-service"
154 host_name = "remote-windows-host"
156 check_command = "nscp"
158 vars.nscp_variable = "USEDDISKSPACE"
159 vars.nscp_params = "c"
164 For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).
166 ## <a id="agent-based-checks-nsca-ng"></a> NSCA-NG
168 [NSCA-ng](http://www.nsca-ng.org) provides a client-server pair that allows the
169 remote sender to push check results into the Icinga 2 `ExternalCommandListener`
174 > This addon works in a similar fashion like the Icinga 1.x distributed model. If you
175 > are looking for a real distributed architecture with Icinga 2, scroll down.
178 ## <a id="agent-based-checks-snmp-traps"></a> Passive Check Results and SNMP Traps
180 SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourceforge.net/)
181 and specific trap handlers passing the check results to Icinga 2.
183 Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT)
184 documentation and the Icinga external command syntax found [here](24-appendix.md#external-commands-list-detail)
185 we can create generic services that can accommodate any number of hosts for a given scenario.
187 ### <a id="simple-traps"></a> Simple SNMP Traps
189 A simple example might be monitoring host reboots indicated by an SNMP agent reset.
190 Building the event to auto reset after dispatching a notification is important.
191 Setup the manual check parameters to reset the event from an initial unhandled
192 state or from a missed reset event.
194 Add a directive in `snmptt.conf`
196 EVENT coldStart .1.3.6.1.6.3.1.1.5.1 "Status Events" Normal
197 FORMAT Device reinitialized (coldStart)
198 EXEC echo "[$@] PROCESS_SERVICE_CHECK_RESULT;$A;Coldstart;2;The snmp agent has reinitialized." >> /var/run/icinga2/cmd/icinga2.cmd
200 A coldStart trap signifies that the SNMPv2 entity, acting
201 in an agent role, is reinitializing itself and that its
202 configuration may have been altered.
205 1. Define the `EVENT` as per your need.
206 2. Construct the `EXEC` statement with the service name matching your template
207 applied to your _n_ hosts. The host address inferred by SNMPTT will be the
208 correlating factor. You can have snmptt provide host names or ip addresses to
209 match your Icinga convention.
211 Add an `EventCommand` configuration object for the passive service auto reset event.
213 object EventCommand "coldstart-reset-event" {
214 import "plugin-event-command"
216 command = [ SysconfDir + "/icinga2/conf.d/custom/scripts/coldstart_reset_event.sh" ]
219 "-i" = "$service.state_id$"
221 "-s" = "$service.name$"
225 Create the `coldstart_reset_event.sh` shell script to pass the expanded variable
226 data in. The `$service.state_id$` is important in order to prevent an endless loop
227 of event firing after the service has been reset.
238 Usage: ${0##*/} [-h] -n HOST_NAME -s SERVICE_NAME
239 Writes a coldstart reset event to the Icinga command pipe.
241 -h Display this help and exit.
242 -i SERVICE_STATE_ID The associated service state id.
243 -n HOST_NAME The associated host name.
244 -s SERVICE_NAME The associated service name.
248 while getopts "hi:n:s:" opt; do
255 SERVICE_STATE_ID=$OPTARG
270 if [ -z "$SERVICE_STATE_ID" ]; then
272 printf "\n Error: -i required.\n"
276 if [ -z "$HOST_NAME" ]; then
278 printf "\n Error: -n required.\n"
282 if [ -z "$SERVICE_NAME" ]; then
284 printf "\n Error: -s required.\n"
288 if [ "$SERVICE_STATE_ID" -gt 0 ]; then
289 echo "[`date +%s`] PROCESS_SERVICE_CHECK_RESULT;$HOST_NAME;$SERVICE_NAME;0;Auto-reset (`date +"%m-%d-%Y %T"`)." >> /var/run/icinga2/cmd/icinga2.cmd
292 Finally create the `Service` and assign it:
294 apply Service "Coldstart" {
295 import "generic-service-custom"
297 check_command = "dummy"
298 event_command = "coldstart-reset-event"
300 enable_notifications = 1
301 enable_active_checks = 0
302 enable_passive_checks = 1
308 vars.dummy_text = "Manual reset."
312 assign where (host.vars.os == "Linux" || host.vars.os == "Windows")
315 ### <a id="complex-traps"></a> Complex SNMP Traps
317 A more complex example might be passing dynamic data from a traps varbind list
318 for a backup scenario where the backup software dispatches status updates. By
319 utilizing active and passive checks, the older freshness concept can be leveraged.
321 By defining the active check as a hard failed state, a missed backup can be reported.
322 As long as the most recent passive update has occurred, the active check is bypassed.
324 Add a directive in `snmptt.conf`
326 EVENT enterpriseSpecific <YOUR OID> "Status Events" Normal
327 FORMAT Enterprise specific trap
328 EXEC echo "[$@] PROCESS_SERVICE_CHECK_RESULT;$A;$1;$2;$3" >> /var/run/icinga2/cmd/icinga2.cmd
330 An enterprise specific trap.
331 The varbinds in order denote the Icinga service name, state and text.
334 1. Define the `EVENT` as per your need using your actual oid.
335 2. The service name, state and text are extracted from the first three varbinds.
336 This has the advantage of accommodating an unlimited set of use cases.
338 Create a `Service` for the specific use case associated to the host. If the host
339 matches and the first varbind value is `Backup`, SNMPTT will submit the corresponding
340 passive update with the state and text from the second and third varbind:
342 object Service "Backup" {
343 import "generic-service-custom"
345 host_name = "host.domain.com"
346 check_command = "dummy"
348 enable_notifications = 1
349 enable_active_checks = 1
350 enable_passive_checks = 1
353 max_check_attempts = 1
354 check_interval = 87000
359 vars.dummy_text = "No passive check result received."