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