granicus.if.org Git - icinga2/blob - doc/07-agent-based-monitoring.md

   1 # Additional Agent-based Checks <a id="agent-based-checks-addon"></a>
   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 ## SNMP <a id="agent-based-checks-snmp"></a>
   8
   9 The SNMP daemon runs on the remote system and answers SNMP queries by plugin
  10 binaries. The [Monitoring Plugins package](02-getting-started.md#setting-up-check-plugins) ships
  11 the `check_snmp` plugin binary, but there are plenty of [existing plugins](05-service-monitoring.md#service-monitoring-plugins)
  12 for specific use cases already around, for example monitoring Cisco routers.
  13
  14 The following example uses the [SNMP ITL](10-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 ```
  19 apply Service "uptime" {
  20   import "generic-service"
  21
  22   check_command = "snmp"
  23   vars.snmp_oid = "1.3.6.1.2.1.1.3.0"
  24   vars.snmp_miblist = "DISMAN-EVENT-MIB"
  25
  26   assign where host.vars.snmp_community != ""
  27 }
  28 ```
  29
  30 Additional SNMP plugins are available using the [Manubulon SNMP Plugins](10-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
  31
  32 If no `snmp_miblist` is specified, the plugin will default to `ALL`. As the number of available MIB files
  33 on the system increases so will the load generated by this plugin if no `MIB` is specified.
  34 As such, it is recommended to always specify at least one `MIB`.
  35
  36 ## SSH <a id="agent-based-checks-ssh"></a>
  37
  38 Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching
  39 its return code and output. The `by_ssh` command object is part of the built-in templates and
  40 requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](02-getting-started.md#setting-up-check-plugins).
  41
  42 ```
  43 object CheckCommand "by_ssh_swap" {
  44   import "by_ssh"
  45
  46   vars.by_ssh_command = "/usr/lib/nagios/plugins/check_swap -w $by_ssh_swap_warn$ -c $by_ssh_swap_crit$"
  47   vars.by_ssh_swap_warn = "75%"
  48   vars.by_ssh_swap_crit = "50%"
  49 }
  50
  51 object Service "swap" {
  52   import "generic-service"
  53
  54   host_name = "remote-ssh-host"
  55
  56   check_command = "by_ssh_swap"
  57
  58   vars.by_ssh_logname = "icinga"
  59 }
  60 ```
  61
  62 ## NSClient++ <a id="agent-based-checks-nsclient"></a>
  63
  64 [NSClient++](https://nsclient.org/) works on both Windows and Linux platforms and is well
  65 known for its magnificent Windows support. There are alternatives like the WMI interface,
  66 but using `NSClient++` will allow you to run local scripts similar to check plugins fetching
  67 the required output and performance counters.
  68
  69 You can use the `check_nt` plugin from the Monitoring Plugins project to query NSClient++.
  70 Icinga 2 provides the [nscp check command](10-icinga-template-library.md#plugin-check-command-nscp) for this:
  71
  72 Example:
  73
  74 ```
  75 object Service "disk" {
  76   import "generic-service"
  77
  78   host_name = "remote-windows-host"
  79
  80   check_command = "nscp"
  81
  82   vars.nscp_variable = "USEDDISKSPACE"
  83   vars.nscp_params = "c"
  84   vars.nscp_warn = 70
  85   vars.nscp_crit = 80
  86 }
  87 ```
  88
  89 For details on the `NSClient++` configuration please refer to the [official documentation](https://docs.nsclient.org/).
  90
  91 ## NSCA-NG <a id="agent-based-checks-nsca-ng"></a>
  92
  93 [NSCA-ng](http://www.nsca-ng.org) provides a client-server pair that allows the
  94 remote sender to push check results into the Icinga 2 `ExternalCommandListener`
  95 feature.
  96
  97 > **Note**
  98 >
  99 > This addon works in a similar fashion like the Icinga 1.x distributed model. If you
 100 > are looking for a real distributed architecture with Icinga 2, scroll down.
 101
 102 ## NRPE <a id="agent-based-checks-nrpe"></a>
 103
 104 [NRPE](https://docs.icinga.com/latest/en/nrpe.html) runs as daemon on the remote client including
 105 the required plugins and command definitions.
 106 Icinga 2 calls the `check_nrpe` plugin binary in order to query the configured command on the
 107 remote client.
 108
 109 > **Note**
 110 >
 111 > The NRPE protocol is considered insecure and has multiple flaws in its
 112 > design. Upstream is not willing to fix these issues.
 113 >
 114 > In order to stay safe, please use the native [Icinga 2 client](06-distributed-monitoring.md#distributed-monitoring)
 115 > instead.
 116
 117 The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
 118 can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
 119
 120 You can use the `check_nrpe` plugin from the NRPE project to query the NRPE daemon.
 121 Icinga 2 provides the [nrpe check command](10-icinga-template-library.md#plugin-check-command-nrpe) for this:
 122
 123 Example:
 124
 125 ```
 126 object Service "users" {
 127   import "generic-service"
 128
 129   host_name = "remote-nrpe-host"
 130
 131   check_command = "nrpe"
 132   vars.nrpe_command = "check_users"
 133 }
 134 ```
 135
 136 nrpe.cfg:
 137
 138 ```
 139 command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
 140 ```
 141
 142 If you are planning to pass arguments to NRPE using the `-a`
 143 command line parameter, make sure that your NRPE daemon has them
 144 supported and enabled.
 145
 146 > **Note**
 147 >
 148 > Enabling command arguments in NRPE is considered harmful
 149 > and exposes a security risk allowing attackers to execute
 150 > commands remotely. Details at [seclists.org](http://seclists.org/fulldisclosure/2014/Apr/240).
 151
 152 The plugin check command `nrpe` provides the `nrpe_arguments` custom
 153 attribute which expects either a single value or an array of values.
 154
 155 Example:
 156
 157 ```
 158 object Service "nrpe-disk-/" {
 159   import "generic-service"
 160
 161   host_name = "remote-nrpe-host"
 162
 163   check_command = "nrpe"
 164   vars.nrpe_command = "check_disk"
 165   vars.nrpe_arguments = [ "20%", "10%", "/" ]
 166 }
 167 ```
 168
 169 Icinga 2 will execute the nrpe plugin like this:
 170
 171 ```
 172 /usr/lib/nagios/plugins/check_nrpe -H <remote-nrpe-host> -c 'check_disk' -a '20%' '10%' '/'
 173 ```
 174
 175 NRPE expects all additional arguments in an ordered fashion
 176 and interprets the first value as `$ARG1$` macro, the second
 177 value as `$ARG2$`, and so on.
 178
 179 nrpe.cfg:
 180
 181 ```
 182 command[check_disk]=/usr/local/icinga/libexec/check_disk -w $ARG1$ -c $ARG2$ -p $ARG3$
 183 ```
 184
 185 Using the above example with `nrpe_arguments` the command
 186 executed by the NRPE daemon looks similar to that:
 187
 188 ```
 189 /usr/local/icinga/libexec/check_disk -w 20% -c 10% -p /
 190 ```
 191
 192 You can pass arguments in a similar manner to [NSClient++](07-agent-based-monitoring.md#agent-based-checks-nsclient)
 193 when using its NRPE supported check method.
 194
 195
 196 ## Passive Check Results and SNMP Traps <a id="agent-based-checks-snmp-traps"></a>
 197
 198 SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourceforge.net/)
 199 and specific trap handlers passing the check results to Icinga 2.
 200
 201 Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT)
 202 documentation and the Icinga external command syntax found [here](24-appendix.md#external-commands-list-detail)
 203 we can create generic services that can accommodate any number of hosts for a given scenario.
 204
 205 ### Simple SNMP Traps <a id="simple-traps"></a>
 206
 207 A simple example might be monitoring host reboots indicated by an SNMP agent reset.
 208 Building the event to auto reset after dispatching a notification is important.
 209 Setup the manual check parameters to reset the event from an initial unhandled
 210 state or from a missed reset event.
 211
 212 Add a directive in `snmptt.conf`
 213
 214 ```
 215 EVENT coldStart .1.3.6.1.6.3.1.1.5.1 "Status Events" Normal
 216 FORMAT Device reinitialized (coldStart)
 217 EXEC echo "[$@] PROCESS_SERVICE_CHECK_RESULT;$A;Coldstart;2;The snmp agent has reinitialized." >> /var/run/icinga2/cmd/icinga2.cmd
 218 SDESC
 219 A coldStart trap signifies that the SNMPv2 entity, acting
 220 in an agent role, is reinitializing itself and that its
 221 configuration may have been altered.
 222 EDESC
 223 ```
 224
 225 1. Define the `EVENT` as per your need.
 226 2. Construct the `EXEC` statement with the service name matching your template
 227 applied to your _n_ hosts. The host address inferred by SNMPTT will be the
 228 correlating factor. You can have snmptt provide host names or ip addresses to
 229 match your Icinga convention.
 230
 231 Add an `EventCommand` configuration object for the passive service auto reset event.
 232
 233 ```
 234 object EventCommand "coldstart-reset-event" {
 235   command = [ ConfigDir + "/conf.d/custom/scripts/coldstart_reset_event.sh" ]
 236
 237   arguments = {
 238     "-i" = "$service.state_id$"
 239     "-n" = "$host.name$"
 240     "-s" = "$service.name$"
 241   }
 242 }
 243 ```
 244
 245 Create the `coldstart_reset_event.sh` shell script to pass the expanded variable
 246 data in. The `$service.state_id$` is important in order to prevent an endless loop
 247 of event firing after the service has been reset.
 248
 249 ```
 250 #!/bin/bash
 251
 252 SERVICE_STATE_ID=""
 253 HOST_NAME=""
 254 SERVICE_NAME=""
 255
 256 show_help()
 257 {
 258 cat <<-EOF
 259         Usage: ${0##*/} [-h] -n HOST_NAME -s SERVICE_NAME
 260         Writes a coldstart reset event to the Icinga command pipe.
 261
 262           -h                  Display this help and exit.
 263           -i SERVICE_STATE_ID The associated service state id.
 264           -n HOST_NAME        The associated host name.
 265           -s SERVICE_NAME     The associated service name.
 266 EOF
 267 }
 268
 269 while getopts "hi:n:s:" opt; do
 270     case "$opt" in
 271       h)
 272           show_help
 273           exit 0
 274           ;;
 275       i)
 276           SERVICE_STATE_ID=$OPTARG
 277           ;;
 278       n)
 279           HOST_NAME=$OPTARG
 280           ;;
 281       s)
 282           SERVICE_NAME=$OPTARG
 283           ;;
 284       '?')
 285           show_help
 286           exit 0
 287           ;;
 288       esac
 289 done
 290
 291 if [ -z "$SERVICE_STATE_ID" ]; then
 292     show_help
 293     printf "\n  Error: -i required.\n"
 294     exit 1
 295 fi
 296
 297 if [ -z "$HOST_NAME" ]; then
 298     show_help
 299     printf "\n  Error: -n required.\n"
 300     exit 1
 301 fi
 302
 303 if [ -z "$SERVICE_NAME" ]; then
 304     show_help
 305     printf "\n  Error: -s required.\n"
 306     exit 1
 307 fi
 308
 309 if [ "$SERVICE_STATE_ID" -gt 0 ]; then
 310     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
 311 fi
 312 ```
 313
 314 Finally create the `Service` and assign it:
 315
 316 ```
 317 apply Service "Coldstart" {
 318   import "generic-service-custom"
 319
 320   check_command         = "dummy"
 321   event_command         = "coldstart-reset-event"
 322
 323   enable_notifications  = 1
 324   enable_active_checks  = 0
 325   enable_passive_checks = 1
 326   enable_flapping       = 0
 327   volatile              = 1
 328   enable_perfdata       = 0
 329
 330   vars.dummy_state      = 0
 331   vars.dummy_text       = "Manual reset."
 332
 333   vars.sla              = "24x7"
 334
 335   assign where (host.vars.os == "Linux" || host.vars.os == "Windows")
 336 }
 337 ```
 338
 339 ### Complex SNMP Traps <a id="complex-traps"></a>
 340
 341 A more complex example might be passing dynamic data from a traps varbind list
 342 for a backup scenario where the backup software dispatches status updates. By
 343 utilizing active and passive checks, the older freshness concept can be leveraged.
 344
 345 By defining the active check as a hard failed state, a missed backup can be reported.
 346 As long as the most recent passive update has occurred, the active check is bypassed.
 347
 348 Add a directive in `snmptt.conf`
 349
 350 ```
 351 EVENT enterpriseSpecific <YOUR OID> "Status Events" Normal
 352 FORMAT Enterprise specific trap
 353 EXEC echo "[$@] PROCESS_SERVICE_CHECK_RESULT;$A;$1;$2;$3" >> /var/run/icinga2/cmd/icinga2.cmd
 354 SDESC
 355 An enterprise specific trap.
 356 The varbinds in order denote the Icinga service name, state and text.
 357 EDESC
 358 ```
 359
 360 1. Define the `EVENT` as per your need using your actual oid.
 361 2. The service name, state and text are extracted from the first three varbinds.
 362 This has the advantage of accommodating an unlimited set of use cases.
 363
 364 Create a `Service` for the specific use case associated to the host. If the host
 365 matches and the first varbind value is `Backup`, SNMPTT will submit the corresponding
 366 passive update with the state and text from the second and third varbind:
 367
 368 ```
 369 object Service "Backup" {
 370   import "generic-service-custom"
 371
 372   host_name             = "host.domain.com"
 373   check_command         = "dummy"
 374
 375   enable_notifications  = 1
 376   enable_active_checks  = 1
 377   enable_passive_checks = 1
 378   enable_flapping       = 0
 379   volatile              = 1
 380   max_check_attempts    = 1
 381   check_interval        = 87000
 382   enable_perfdata       = 0
 383
 384   vars.sla              = "24x7"
 385   vars.dummy_state      = 2
 386   vars.dummy_text       = "No passive check result received."
 387 }
 388 ```