granicus.if.org Git - icinga2/blob - doc/05-service-monitoring.md

   1 # Service Monitoring <a id="service-monitoring"></a>
   2
   3 The power of Icinga 2 lies in its modularity. There are thousands of
   4 community plugins available next to the standard plugins provided by
   5 the [Monitoring Plugins project](https://www.monitoring-plugins.org).
   6
   7 ## Requirements <a id="service-monitoring-requirements"></a>
   8
   9 ### Plugins <a id="service-monitoring-plugins"></a>
  10
  11 All existing Nagios or Icinga 1.x plugins work with Icinga 2. Community
  12 plugins can be found for example on [Icinga Exchange](https://exchange.icinga.com).
  13
  14 The recommended way of setting up these plugins is to copy them to a common directory
  15 and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](04-configuring-icinga-2.md#constants-conf)
  16 configuration file:
  17
  18 ```
  19 # cp check_snmp_int.pl /opt/monitoring/plugins
  20 # chmod +x /opt/monitoring/plugins/check_snmp_int.pl
  21
  22 # cat /etc/icinga2/constants.conf
  23 /**
  24  * This file defines global constants which can be used in
  25  * the other configuration files. At a minimum the
  26  * PluginDir constant should be defined.
  27  */
  28
  29 const PluginDir = "/usr/lib/nagios/plugins"
  30 const CustomPluginDir = "/opt/monitoring/plugins"
  31 ```
  32
  33 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
  34 by trying to run it on the console using whichever user Icinga 2 is running as:
  35
  36 ```
  37 # su - icinga -s /bin/bash
  38 $ /opt/monitoring/plugins/check_snmp_int.pl --help
  39 ```
  40
  41 Additional libraries may be required for some plugins. Please consult the plugin
  42 documentation and/or the included README file for installation instructions.
  43 Sometimes plugins contain hard-coded paths to other components. Instead of changing
  44 the plugin it might be easier to create a symbolic link to make sure it doesn't get overwritten during the next update.
  45
  46 Sometimes there are plugins which do not exactly fit your requirements.
  47 In that case you can modify an existing plugin or just write your own.
  48
  49 ### CheckCommand Definition <a id="service-monitoring-plugin-checkcommand"></a>
  50
  51 Each plugin requires a [CheckCommand](09-object-types.md#objecttype-checkcommand) object in your
  52 configuration which can be used in the [Service](09-object-types.md#objecttype-service) or
  53 [Host](09-object-types.md#objecttype-host) object definition.
  54
  55 Please check if the Icinga 2 package already provides an
  56 [existing CheckCommand definition](10-icinga-template-library.md#icinga-template-library).
  57 If that's the case, throroughly check the required parameters and integrate the check command
  58 into your host and service objects.
  59
  60 Please make sure to follow these conventions when adding a new command object definition:
  61
  62 * Use [command arguments](03-monitoring-basics.md#command-arguments) whenever possible. The `command` attribute
  63 must be an array in `[ ... ]` for shell escaping.
  64 * Define a unique `prefix` for the command's specific arguments. That way you can safely
  65 set them on host/service level and you'll always know which command they control.
  66 * Use command argument default values, e.g. for thresholds.
  67 * Use [advanced conditions](09-object-types.md#objecttype-checkcommand) like `set_if` definitions.
  68
  69 This is an example for a custom `my-snmp-int` check command:
  70
  71 ```
  72 object CheckCommand "my-snmp-int" {
  73   command = [ CustomPluginDir + "/check_snmp_int.pl" ]
  74
  75   arguments = {
  76     "-H" = "$snmp_address$"
  77     "-C" = "$snmp_community$"
  78     "-p" = "$snmp_port$"
  79     "-2" = {
  80       set_if = "$snmp_v2$"
  81     }
  82     "-n" = "$snmp_interface$"
  83     "-f" = {
  84       set_if = "$snmp_perf$"
  85     }
  86     "-w" = "$snmp_warn$"
  87     "-c" = "$snmp_crit$"
  88   }
  89
  90   vars.snmp_v2 = true
  91   vars.snmp_perf = true
  92   vars.snmp_warn = "300,400"
  93   vars.snmp_crit = "0,600"
  94 }
  95 ```
  96
  97 For further information on your monitoring configuration read the
  98 [Monitoring Basics](03-monitoring-basics.md#monitoring-basics) chapter.
  99
 100 If you have created your own `CheckCommand` definition, please kindly
 101 [send it upstream](https://github.com/Icinga/icinga2/blob/master/CONTRIBUTING.md).
 102
 103 ### Plugin API <a id="service-monitoring-plugin-api"></a>
 104
 105 Currently Icinga 2 supports the native plugin API specification from the Monitoring Plugins project. It is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
 106
 107 ### Create a new Plugin <a id="service-monitoring-plugin-new"></a>
 108
 109 Sometimes an existing plugin does not satisfy your requirements. You
 110 can either kindly contact the original author about plans to add changes
 111 and/or create a patch.
 112
 113 If you just want to format the output and state of an existing plugin
 114 it might also be helpful to write a wrapper script. This script
 115 could pass all configured parameters, call the plugin script, parse
 116 its output/exit code and return your specified output/exit code.
 117
 118 On the other hand plugins for specific services and hardware might not yet
 119 exist.
 120
 121 Common best practices when creating a new plugin are for example:
 122
 123 * Choose the programming language wisely
 124  * Scripting languages (Bash, Python, Perl, Ruby, PHP, etc.) are easier to write and setup but their check execution might take longer (invoking the script interpreter as overhead, etc.).
 125  * Plugins written in C/C++, Go, etc. improve check execution time but may generate an overhead with installation and packaging.
 126 * Use a modern VCS such as Git for developing the plugin (e.g. share your plugin on GitHub).
 127 * Add parameters with key-value pairs to your plugin. They should allow long names (e.g. `--host localhost`) and also short parameters (e.g. `-H localhost`)
 128  * `-h|--help` should print the version and all details about parameters and runtime invocation.
 129 * Add a verbose/debug output functionality for detailed on-demand logging.
 130 * Respect the exit codes required by the [Plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
 131 * Always add performance data to your plugin output
 132
 133 Example skeleton:
 134
 135 ```
 136 # 1. include optional libraries
 137 # 2. global variables
 138 # 3. helper functions and/or classes
 139 # 4. define timeout condition
 140
 141 if (<timeout_reached>) then
 142   print "UNKNOWN - Timeout (...) reached | 'time'=30.0
 143 endif
 144
 145 # 5. main method
 146
 147 <execute and fetch data>
 148
 149 if (<threshold_critical_condition>) then
 150   print "CRITICAL - ... | 'time'=0.1 'myperfdatavalue'=5.0
 151   exit(2)
 152 else if (<threshold_warning_condition>) then
 153   print "WARNING - ... | 'time'=0.1 'myperfdatavalue'=3.0
 154   exit(1)
 155 else
 156   print "OK - ... | 'time'=0.2 'myperfdatavalue'=1.0
 157 endif
 158 ```
 159
 160 There are various plugin libraries available which will help
 161 with plugin execution and output formatting too, for example
 162 [nagiosplugin from Python](https://pypi.python.org/pypi/nagiosplugin/).
 163
 164 > **Note**
 165 >
 166 > Ensure to test your plugin properly with special cases before putting it
 167 > into production!
 168
 169 Once you've finished your plugin please upload/sync it to [Icinga Exchange](https://exchange.icinga.com/new).
 170 Thanks in advance!
 171
 172 ## Service Monitoring Overview <a id="service-monitoring-overview"></a>
 173
 174 The following examples should help you to start implementing your own ideas.
 175 There is a variety of plugins available. This collection is not complete --
 176 if you have any updates, please send a documentation patch upstream.
 177
 178 ### General Monitoring <a id="service-monitoring-general"></a>
 179
 180 If the remote service is available (via a network protocol and port),
 181 and if a check plugin is also available, you don't necessarily need a local client.
 182 Instead, choose a plugin and configure its parameters and thresholds. The following examples are included in the [Icinga 2 Template Library](10-icinga-template-library.md#icinga-template-library):
 183
 184 * [ping4](10-icinga-template-library.md#plugin-check-command-ping4), [ping6](10-icinga-template-library.md#plugin-check-command-ping6),
 185 [fping4](10-icinga-template-library.md#plugin-check-command-fping4), [fping6](10-icinga-template-library.md#plugin-check-command-fping6), [hostalive](10-icinga-template-library.md#plugin-check-command-hostalive)
 186 * [tcp](10-icinga-template-library.md#plugin-check-command-tcp), [udp](10-icinga-template-library.md#plugin-check-command-udp), [ssl](10-icinga-template-library.md#plugin-check-command-ssl)
 187 * [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time)
 188
 189 ### Linux Monitoring <a id="service-monitoring-linux"></a>
 190
 191 * [disk](10-icinga-template-library.md#plugin-check-command-disk)
 192 * [mem](10-icinga-template-library.md#plugin-contrib-command-mem), [swap](10-icinga-template-library.md#plugin-check-command-swap)
 193 * [procs](10-icinga-template-library.md#plugin-check-command-processes)
 194 * [users](10-icinga-template-library.md#plugin-check-command-users)
 195 * [running_kernel](10-icinga-template-library.md#plugin-contrib-command-running_kernel)
 196 * package management: [apt](10-icinga-template-library.md#plugin-check-command-apt), [yum](10-icinga-template-library.md#plugin-contrib-command-yum), etc.
 197 * [ssh](10-icinga-template-library.md#plugin-check-command-ssh)
 198 * performance: [iostat](10-icinga-template-library.md#plugin-contrib-command-iostat), [check_sar_perf](https://github.com/dnsmichi/icinga-plugins/blob/master/scripts/check_sar_perf.py)
 199
 200 ### Windows Monitoring <a id="service-monitoring-windows"></a>
 201
 202 * [check_wmi_plus](http://www.edcint.co.nz/checkwmiplus/)
 203 * [NSClient++](https://www.nsclient.org) (in combination with the Icinga 2 client and either [check_nscp_api](10-icinga-template-library.md#nscp-check-api) or [nscp-local](10-icinga-template-library.md#nscp-plugin-check-commands) check commands)
 204 * [Icinga 2 Windows Plugins](10-icinga-template-library.md#windows-plugins) (disk, load, memory, network, performance counters, ping, procs, service, swap, updates, uptime, users
 205 * vbs and Powershell scripts
 206
 207 ### Database Monitoring <a id="service-monitoring-database"></a>
 208
 209 * MySQL/MariaDB: [mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health), [mysql](10-icinga-template-library.md#plugin-check-command-mysql), [mysql_query](10-icinga-template-library.md#plugin-check-command-mysql-query)
 210 * PostgreSQL: [postgres](10-icinga-template-library.md#plugin-contrib-command-postgres)
 211 * Oracle: [oracle_health](10-icinga-template-library.md#plugin-contrib-command-oracle_health)
 212 * MSSQL: [mssql_health](10-icinga-template-library.md#plugin-contrib-command-mssql_health)
 213 * DB2: [db2_health](10-icinga-template-library.md#plugin-contrib-command-db2_health)
 214 * MongoDB: [mongodb](10-icinga-template-library.md#plugin-contrib-command-mongodb)
 215 * Elasticsearch: [elasticsearch](10-icinga-template-library.md#plugin-contrib-command-elasticsearch)
 216 * Redis: [redis](10-icinga-template-library.md#plugin-contrib-command-redis)
 217
 218 ### SNMP Monitoring <a id="service-monitoring-snmp"></a>
 219
 220 * [Manubulon plugins](10-icinga-template-library.md#snmp-manubulon-plugin-check-commands) (interface, storage, load, memory, process)
 221 * [snmp](10-icinga-template-library.md#plugin-check-command-snmp), [snmpv3](10-icinga-template-library.md#plugin-check-command-snmpv3)
 222
 223 ### Network Monitoring <a id="service-monitoring-network"></a>
 224
 225 * [nwc_health](10-icinga-template-library.md#plugin-contrib-command-nwc_health)
 226 * [interfaces](10-icinga-template-library.md#plugin-contrib-command-interfaces)
 227 * [interfacetable](10-icinga-template-library.md#plugin-contrib-command-interfacetable)
 228 * [iftraffic](10-icinga-template-library.md#plugin-contrib-command-iftraffic), [iftraffic64](10-icinga-template-library.md#plugin-contrib-command-iftraffic64)
 229
 230 ### Web Monitoring <a id="service-monitoring-web"></a>
 231
 232 * [http](10-icinga-template-library.md#plugin-check-command-http)
 233 * [ftp](10-icinga-template-library.md#plugin-check-command-ftp)
 234 * [webinject](10-icinga-template-library.md#plugin-contrib-command-webinject)
 235 * [squid](10-icinga-template-library.md#plugin-contrib-command-squid)
 236 * [apache-status](10-icinga-template-library.md#plugin-contrib-command-apache-status)
 237 * [nginx_status](10-icinga-template-library.md#plugin-contrib-command-nginx_status)
 238 * [kdc](10-icinga-template-library.md#plugin-contrib-command-kdc)
 239 * [rbl](10-icinga-template-library.md#plugin-contrib-command-rbl)
 240
 241 ### Java Monitoring <a id="service-monitoring-java"></a>
 242
 243 * [jmx4perl](10-icinga-template-library.md#plugin-contrib-command-jmx4perl)
 244
 245 ### DNS Monitoring <a id="service-monitoring-dns"></a>
 246
 247 * [dns](10-icinga-template-library.md#plugin-check-command-dns)
 248 * [dig](10-icinga-template-library.md#plugin-check-command-dig)
 249 * [dhcp](10-icinga-template-library.md#plugin-check-command-dhcp)
 250
 251 ### Backup Monitoring <a id="service-monitoring-backup"></a>
 252
 253 * [check_bareos](https://github.com/widhalmt/check_bareos)
 254
 255 ### Log Monitoring <a id="service-monitoring-log"></a>
 256
 257 * [check_logfiles](https://labs.consol.de/nagios/check_logfiles/)
 258 * [check_logstash](https://github.com/widhalmt/check_logstash)
 259 * [check_graylog2_stream](https://github.com/Graylog2/check-graylog2-stream)
 260
 261 ### Virtualization Monitoring <a id="service-monitoring-virtualization"></a>
 262
 263 ### VMware Monitoring <a id="service-monitoring-virtualization-vmware"></a>
 264
 265 * [esxi_hardware](10-icinga-template-library.md#plugin-contrib-command-esxi-hardware)
 266 * [VMware](10-icinga-template-library.md#plugin-contrib-vmware)
 267
 268 **Tip**: If you are encountering timeouts using the VMware Perl SDK,
 269 check [this blog entry](https://www.claudiokuenzler.com/blog/650/slow-vmware-perl-sdk-soap-request-error-libwww-version).
 270 Ubuntu 16.04 LTS can have troubles with random entropy in Perl asked [here](https://monitoring-portal.org/t/check-vmware-api-slow-when-run-multiple-times/2868).
 271 In that case, [haveged](http://issihosts.com/haveged/) may help.
 272
 273 ### SAP Monitoring <a id="service-monitoring-sap"></a>
 274
 275 * [check_sap_health](https://labs.consol.de/nagios/check_sap_health/index.html)
 276 * [SAP CCMS](https://sourceforge.net/projects/nagios-sap-ccms/)
 277
 278 ### Mail Monitoring <a id="service-monitoring-mail"></a>
 279
 280 * [smtp](10-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](10-icinga-template-library.md#plugin-check-command-ssmtp)
 281 * [imap](10-icinga-template-library.md#plugin-check-command-imap), [simap](10-icinga-template-library.md#plugin-check-command-simap)
 282 * [pop](10-icinga-template-library.md#plugin-check-command-pop), [spop](10-icinga-template-library.md#plugin-check-command-spop)
 283 * [mailq](10-icinga-template-library.md#plugin-check-command-mailq)
 284
 285 ### Hardware Monitoring <a id="service-monitoring-hardware"></a>
 286
 287 * [hpasm](10-icinga-template-library.md#plugin-contrib-command-hpasm)
 288 * [ipmi-sensor](10-icinga-template-library.md#plugin-contrib-command-ipmi-sensor)
 289
 290 ### Metrics Monitoring <a id="service-monitoring-metrics"></a>
 291
 292 * [graphite](10-icinga-template-library.md#plugin-contrib-command-graphite)