granicus.if.org Git - icinga2/blob - doc/12-agent-based-checks.md

   1 # <a id="agent-based-checks-addon"></a> Additional Agent-based Checks
   2
   3 If the remote services are not directly accessible through the network, a
   4 local agent installation exposing the results to check queries can
   5 become handy.
   6
   7 ## <a id="agent-based-checks-snmp"></a> SNMP
   8
   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.
  13
  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.
  17
  18     apply Service "uptime" {
  19       import "generic-service"
  20
  21       check_command = "snmp"
  22       vars.snmp_oid = "1.3.6.1.2.1.1.3.0"
  23       vars.snmp_miblist = "DISMAN-EVENT-MIB"
  24
  25       assign where host.vars.snmp_community != ""
  26     }
  27
  28 Additional SNMP plugins are available using the [Manubulon SNMP Plugins](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
  29
  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`.
  33
  34 ## <a id="agent-based-checks-ssh"></a> SSH
  35
  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).
  39
  40     object CheckCommand "by_ssh_swap" {
  41       import "by_ssh"
  42
  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%"
  46     }
  47
  48     object Service "swap" {
  49       import "generic-service"
  50
  51       host_name = "remote-ssh-host"
  52
  53       check_command = "by_ssh_swap"
  54
  55       vars.by_ssh_logname = "icinga"
  56     }
  57
  58 ## <a id="agent-based-checks-nrpe"></a> NRPE
  59
  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
  63 remote client.
  64
  65 > **Note**
  66 >
  67 > The NRPE protocol is considered insecure and has multiple flaws in its
  68 > design. Upstream is not willing to fix these issues.
  69 >
  70 > In order to stay safe, please use the native [Icinga 2 client](11-icinga2-client.md#icinga2-client)
  71 > instead.
  72
  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.
  75
  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:
  78
  79 Example:
  80
  81     object Service "users" {
  82       import "generic-service"
  83
  84       host_name = "remote-nrpe-host"
  85
  86       check_command = "nrpe"
  87       vars.nrpe_command = "check_users"
  88     }
  89
  90 nrpe.cfg:
  91
  92     command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
  93
  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.
  97
  98 > **Note**
  99 >
 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).
 103
 104 The plugin check command `nrpe` provides the `nrpe_arguments` custom
 105 attribute which expects either a single value or an array of values.
 106
 107 Example:
 108
 109     object Service "nrpe-disk-/" {
 110       import "generic-service"
 111
 112       host_name = "remote-nrpe-host"
 113
 114       check_command = "nrpe"
 115       vars.nrpe_command = "check_disk"
 116       vars.nrpe_arguments = [ "20%", "10%", "/" ]
 117     }
 118
 119 Icinga 2 will execute the nrpe plugin like this:
 120
 121     /usr/lib/nagios/plugins/check_nrpe -H <remote-nrpe-host> -c 'check_disk' -a '20%' '10%' '/'
 122
 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.
 126
 127 nrpe.cfg:
 128
 129     command[check_disk]=/usr/local/icinga/libexec/check_disk -w $ARG1$ -c $ARG2$ -p $ARG3$
 130
 131 Using the above example with `nrpe_arguments` the command
 132 executed by the NRPE daemon looks similar to that:
 133
 134     /usr/local/icinga/libexec/check_disk -w 20% -c 10% -p /
 135
 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.
 138
 139 ## <a id="agent-based-checks-nsclient"></a> NSClient++
 140
 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.
 145
 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:
 148
 149 Example:
 150
 151     object Service "disk" {
 152       import "generic-service"
 153
 154       host_name = "remote-windows-host"
 155
 156       check_command = "nscp"
 157
 158       vars.nscp_variable = "USEDDISKSPACE"
 159       vars.nscp_params = "c"
 160       vars.nscp_warn = 70
 161       vars.nscp_crit = 80
 162     }
 163
 164 For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).
 165
 166 ## <a id="agent-based-checks-nsca-ng"></a> NSCA-NG
 167
 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`
 170 feature.
 171
 172 > **Note**
 173 >
 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.
 176
 177
 178 ## <a id="agent-based-checks-snmp-traps"></a> Passive Check Results and SNMP Traps
 179
 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.
 182
 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](22-appendix.md#external-commands-list-detail)
 185 we can create generic services that can accommodate any number of hosts for a given scenario.
 186
 187 ### <a id="simple-traps"></a> Simple SNMP Traps
 188
 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.
 193
 194 Add a directive in `snmptt.conf`
 195
 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
 199     SDESC
 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.
 203     EDESC
 204
 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.
 210
 211 Add an `EventCommand` configuration object for the passive service auto reset event.
 212
 213     object EventCommand "coldstart-reset-event" {
 214       import "plugin-event-command"
 215
 216       command = [ SysconfDir + "/icinga2/conf.d/custom/scripts/coldstart_reset_event.sh" ]
 217
 218       arguments = {
 219         "-i" = "$service.state_id$"
 220         "-n" = "$host.name$"
 221         "-s" = "$service.name$"
 222       }
 223     }
 224
 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.
 228
 229     #!/bin/bash
 230
 231     SERVICE_STATE_ID=""
 232     HOST_NAME=""
 233     SERVICE_NAME=""
 234
 235     show_help()
 236     {
 237     cat <<-EOF
 238         Usage: ${0##*/} [-h] -n HOST_NAME -s SERVICE_NAME
 239         Writes a coldstart reset event to the Icinga command pipe.
 240
 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.
 245     EOF
 246     }
 247
 248     while getopts "hi:n:s:" opt; do
 249         case "$opt" in
 250           h)
 251               show_help
 252               exit 0
 253               ;;
 254           i)
 255               SERVICE_STATE_ID=$OPTARG
 256               ;;
 257           n)
 258               HOST_NAME=$OPTARG
 259               ;;
 260           s)
 261               SERVICE_NAME=$OPTARG
 262               ;;
 263           '?')
 264               show_help
 265               exit 0
 266               ;;
 267           esac
 268     done
 269
 270     if [ -z "$SERVICE_STATE_ID" ]; then
 271         show_help
 272         printf "\n  Error: -i required.\n"
 273         exit 1
 274     fi
 275
 276     if [ -z "$HOST_NAME" ]; then
 277         show_help
 278         printf "\n  Error: -n required.\n"
 279         exit 1
 280     fi
 281
 282     if [ -z "$SERVICE_NAME" ]; then
 283         show_help
 284         printf "\n  Error: -s required.\n"
 285         exit 1
 286     fi
 287
 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
 290     fi
 291
 292 Finally create the `Service` and assign it:
 293
 294     apply Service "Coldstart" {
 295       import "generic-service-custom"
 296
 297       check_command         = "dummy"
 298       event_command         = "coldstart-reset-event"
 299
 300       enable_notifications  = 1
 301       enable_active_checks  = 0
 302       enable_passive_checks = 1
 303       enable_flapping       = 0
 304       volatile              = 1
 305       enable_perfdata       = 0
 306
 307       vars.dummy_state      = 0
 308       vars.dummy_text       = "Manual reset."
 309
 310       vars.sla              = "24x7"
 311
 312       assign where (host.vars.os == "Linux" || host.vars.os == "Windows")
 313     }
 314
 315 ### <a id="complex-traps"></a> Complex SNMP Traps
 316
 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.
 320
 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.
 323
 324 Add a directive in `snmptt.conf`
 325
 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
 329     SDESC
 330     An enterprise specific trap.
 331     The varbinds in order denote the Icinga service name, state and text.
 332     EDESC
 333
 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.
 337
 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:
 341
 342     object Service "Backup" {
 343       import "generic-service-custom"
 344
 345       host_name             = "host.domain.com"
 346       check_command         = "dummy"
 347
 348       enable_notifications  = 1
 349       enable_active_checks  = 1
 350       enable_passive_checks = 1
 351       enable_flapping       = 0
 352       volatile              = 1
 353       max_check_attempts    = 1
 354       check_interval        = 87000
 355       enable_perfdata       = 0
 356
 357       vars.sla              = "24x7"
 358       vars.dummy_state      = 2
 359       vars.dummy_text       = "No passive check result received."
 360     }