granicus.if.org Git - icinga2/blob - doc/14-addons-plugins.md

   1 # <a id="addons-plugins"></a> Icinga 2 Addons and Plugins
   2
   3 ## <a id="addons-graphing"></a> Graphing
   4
   5 ### <a id="addons-graphing-pnp"></a> PNP
   6
   7 [PNP](http://www.pnp4nagios.org) is a graphing addon.
   8
   9 [PNP](http://www.pnp4nagios.org) is an addon which adds a graphical representation of the performance data collected
  10 by the monitoring plugins. The data is stored as rrd (round robin database) files.
  11
  12 Use your distribution's package manager to install the `pnp4nagios` package.
  13
  14 If you're planning to use it configure it to use the
  15 [bulk mode with npcd and npcdmod](http://docs.pnp4nagios.org/pnp-0.6/modes#bulk_mode_with_npcd_and_npcdmod)
  16 in combination with Icinga 2's [PerfdataWriter](15-features.md#performance-data). NPCD collects the performance
  17 data files which Icinga 2 generates.
  18
  19 Enable performance data writer in icinga 2
  20
  21     # icinga2 feature enable perfdata
  22
  23 Configure npcd to use the performance data created by Icinga 2:
  24
  25     vim /etc/pnp4nagios/npcd.cfg
  26
  27 Set `perfdata_spool_dir = /var/spool/icinga2/perfdata` and restart the `npcd` daemon.
  28
  29 There's also an Icinga Web 2 module for direct PNP graph integration
  30 available at https://exchange.icinga.org/icinga/PNP4Nagios
  31
  32 More information on [action_url as attribute](14-addons-plugins.md#addons-graphing-pnp-action-url)
  33 and [graph template names](14-addons-plugins.md#addons-graphing-pnp-custom-templates).
  34
  35
  36 ### <a id="addons-graphing-graphite"></a> Graphite
  37
  38 [Graphite](http://graphite.readthedocs.org/en/latest/) is a time-series database
  39 storing collected metrics and making them available through restful apis
  40 and web interfaces.
  41
  42 Graphite consists of 3 software components:
  43
  44 * carbon - a Twisted daemon that listens for time-series data
  45 * whisper - a simple database library for storing time-series data (similar in design to RRD)
  46 * graphite webapp - A Django webapp that renders graphs on-demand using Cairo
  47
  48 Use the [GraphiteWriter](15-features.md#graphite-carbon-cache-writer) feature
  49 for sending real-time metrics from Icinga 2 to Graphite.
  50
  51     # icinga2 feature enable graphite
  52
  53 There are Graphite addons available for collecting the performance data files too (e.g. `Graphios`).
  54
  55 A popular alternative frontend for Graphite is for example [Grafana](http://grafana.org).
  56
  57 ### <a id="addons-graphing-influxdb"></a> InfluxDB
  58
  59 [InfluxDB](https://influxdb.com) is a time series, metrics, and analytics database.
  60 It’s written in Go and has no external dependencies.
  61
  62 Use the [GraphiteWriter](15-features.md#graphite-carbon-cache-writer) feature
  63 for sending real-time metrics from Icinga 2 to InfluxDB. Note: There are [API changes](https://github.com/influxdb/influxdb/issues/2102)
  64 in InfluxDB 0.9.x.
  65
  66     # icinga2 feature enable graphite
  67
  68 A popular frontend for InfluxDB is for example [Grafana](http://grafana.org).
  69
  70 ## <a id="addons-visualization"></a> Visualization
  71
  72 ### <a id="addons-visualization-reporting"></a> Icinga Reporting
  73
  74 By enabling the [DB IDO](15-features.md#db-ido) feature you can use the
  75 [Icinga Reporting package](https://wiki.icinga.org/display/howtos/Setting+up+Icinga+with+Reporting).
  76
  77 ### <a id="addons-visualization-nagvis"></a> NagVis
  78
  79 By using either [Livestatus](15-features.md#setting-up-livestatus) or
  80 [DB IDO](15-features.md#db-ido) as a backend you can create your own network maps
  81 based on your monitoring configuration and status data using [NagVis](http://www.nagvis.org).
  82
  83 The configuration in nagvis.ini.php should look like this for Livestatus for example:
  84
  85     [backend_live_1]
  86     backendtype="mklivestatus"
  87     socket="unix:/var/run/icinga2/cmd/livestatus"
  88
  89 If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/divetoh/icingaweb2-module-nagvis).
  90
  91 ### <a id="addons-visualization-thruk"></a> Thruk
  92
  93 [Thruk](http://www.thruk.org) is an alternative web interface which can be used with Icinga 2
  94 and the [Livestatus](15-features.md#setting-up-livestatus) feature.
  95
  96 ## <a id="log-monitoring"></a> Log Monitoring
  97
  98 Using [Logstash](https://www.elastic.co/guide/en/logstash/current/introduction.html) or
  99 [Graylog](https://www.graylog.org) in your infrastructure and correlate events with your monitoring
 100 is even simpler these days.
 101
 102 * Use the `GelfWriter` feature to write Icinga 2's check and notification events to Graylog or Logstash.
 103 * Configure the logstash `nagios` output to send passive traps to Icinga 2 using the external command pipe.
 104 * Execute a plugin to check Graylog alert streams.
 105
 106 More details can be found in [this blog post](https://www.icinga.org/2014/12/02/team-icinga-at-osmc-2014/).
 107
 108 ## <a id="notification-scripts-interfaces"></a> Notification Scripts and Interfaces
 109
 110 There's a variety of resources available, be it different notification scripts such as:
 111
 112 * E-Mail ([examples](3-monitoring-basics.md#notifications) provided)
 113 * SMS
 114 * Pager (XMPP, etc.)
 115 * Twitter
 116 * IRC
 117 * Ticket systems
 118 * etc.
 119
 120 Additionally external services can be [integrated with Icinga 2](https://www.icinga.org/icinga/integration/):
 121
 122 * [Pagerduty](https://www.icinga.org/partners/pagerduty/)
 123 * [VictorOps](https://www.icinga.org/partners/victorops/)
 124 * [StackStorm](https://www.icinga.org/partners/stackstorm/)
 125
 126 More information can be found on the [Icinga Website](https://www.icinga.org)
 127 and the [Icinga Wiki](https://wiki.icinga.org/display/howtos/Home).
 128
 129 ## <a id="configuration-tools"></a> Configuration Management Tools
 130
 131 If you require your favourite configuration tool to export Icinga 2 configuration, please get in
 132 touch with their developers. The Icinga project does not provide a configuration web interface
 133 yet. Follow the [Icinga Blog](https://www.icinga.org/blog/) for updates on this topic.
 134
 135 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
 136 to integrate them upstream, so please get in touch with the [Icinga team](https://www.icinga.org/community/get-involved/).
 137
 138 These tools are currently in development and require feedback and tests:
 139
 140 * [Ansible Roles](https://github.com/Icinga/icinga2-ansible)
 141 * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
 142 * [Chef Cookbook](https://github.com/Icinga/chef-icinga2)
 143
 144 ## <a id="plugins"></a> Plugins
 145
 146 For some services you may need additional 'check plugins' which are not provided
 147 by the official Monitoring Plugins project.
 148
 149 All existing Nagios or Icinga 1.x plugins work with Icinga 2. Here's a
 150 list of popular community sites which host check plugins:
 151
 152 * [Icinga Exchange](https://exchange.icinga.org)
 153 * [Icinga Wiki](https://wiki.icinga.org)
 154
 155 The recommended way of setting up these plugins is to copy them to a common directory
 156 and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](4-configuring-icinga-2.md#constants-conf)
 157 configuration file:
 158
 159     # cp check_snmp_int.pl /opt/monitoring/plugins
 160     # chmod +x /opt/plugins/check_snmp_int.pl
 161
 162     # cat /etc/icinga2/constants.conf
 163     /**
 164      * This file defines global constants which can be used in
 165      * the other configuration files. At a minimum the
 166      * PluginDir constant should be defined.
 167      */
 168
 169     const PluginDir = "/usr/lib/nagios/plugins"
 170     const CustomPluginDir = "/opt/monitoring/plugins"
 171
 172 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
 173 by trying to run it on the console using whichever user Icinga 2 is running as:
 174
 175     # su - icinga -s /bin/bash
 176     $ /opt/monitoring/plugins/check_snmp_int.pl --help
 177
 178 Additional libraries may be required for some plugins. Please consult the plugin
 179 documentation and/or plugin provided README for installation instructions.
 180 Sometimes plugins contain hard-coded paths to other components. Instead of changing
 181 the plugin it might be easier to create logical links which is (more) update-safe.
 182
 183 Each plugin requires a [CheckCommand](6-object-types.md#objecttype-checkcommand) object in your
 184 configuration which can be used in the [Service](6-object-types.md#objecttype-service) or
 185 [Host](6-object-types.md#objecttype-host) object definition.
 186
 187 There are the following conventions to follow when adding a new command object definition:
 188
 189 * Always import the `plugin-check-command` template
 190 * Use [command-arguments](#) whenever possible. The `command` attribute must be an array
 191 in `[ ... ]` then for shell escaping.
 192 * Define a unique `prefix` for the command's specific command arguments. That way you can safely
 193 set them on host/service level and you'll always know which command they control.
 194 * Use command argument default values, e.g. for thresholds
 195 * Use [advanced conditions](6-object-types.md#objecttype-checkcommand) like `set_if` definitions.
 196
 197 Example for a custom `my-snmp-int` check command:
 198
 199     object CheckCommand "my-snmp-int" {
 200       import "plugin-check-command"
 201
 202       command = [ CustomPluginDir + "/check_snmp_int.pl" ]
 203
 204       arguments = {
 205         "-H" = "$snmp_address$"
 206         "-C" = "$snmp_community$"
 207         "-p" = "$snmp_port$"
 208         "-2" = {
 209           set_if = "$snmp_v2$"
 210         }
 211         "-n" = "$snmp_interface$"
 212         "-f" = {
 213           set_if = "$snmp_perf$"
 214         }
 215         "-w" = "$snmp_warn$"
 216         "-c" = "$snmp_crit$"
 217       }
 218
 219       vars.snmp_v2 = true
 220       vars.snmp_perf = true
 221       vars.snmp_warn = "300,400"
 222       vars.snmp_crit = "0,600"
 223     }
 224
 225 Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
 226
 227 For further information on your monitoring configuration read the
 228 [Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
 229
 230 You can find additional plugins at the [Icinga Exchange](https://exchange.icinga.org)
 231
 232 More details on the plugins can also be found on the Icinga Wiki at https://wiki.icinga.org
 233
 234 > **Tip**
 235 >
 236 > Create the best `CheckCommand` definition there is and send it upstream. More
 237 > information can be found in [Contribute Icinga 2 ITL Plugin Check Command Definitions](https://wiki.icinga.org/display/community/Contribute+Icinga+2+ITL+Plugin+Check+Command+Definitions)
 238 > on the Icinga Wiki. Thank you in advance!
 239
 240 ## <a id="plugin-api"></a> Plugin API
 241
 242 Currently Icinga 2 supports the native plugin API specification from the `Monitoring Plugins`
 243 project.
 244
 245 The `Monitoring Plugin API` is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
 246
 247 There are no output length restrictions using Icinga 2. This is different to the
 248 [Icinga 1.x plugin api definition](http://docs.icinga.org/latest/en/pluginapi.html#outputlengthrestrictions).
 249
 250
 251 ## <a id="addon-integration-hints"></a> More Addon Integration Hints
 252
 253 ### <a id="addons-graphing-pnp-action-url"></a> PNP Action Url
 254
 255 They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require
 256 the action url attribute in its own module).
 257
 258     template Service "pnp-hst" {
 259       action_url = "/pnp4nagios/graph?host=$HOSTNAME$"
 260     }
 261
 262     template Service "pnp-svc" {
 263       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 264     }
 265
 266 ### <a id="addons-graphing-pnp-custom-templates"></a> PNP Custom Templates with Icinga 2
 267
 268 PNP automatically determines the graph template from the check command name (or the argument's name).
 269 This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to
 270 fix this:
 271
 272 * Create a symlink for example from the `templates.dist/check_ping.php` template to the actual check name in Icinga 2 (`templates/ping4.php`)
 273 * Pass the check command name inside the [format template configuration](15-features.md#writing-performance-data-files)
 274
 275 The latter becomes difficult with agent based checks like NRPE or SSH where the first command argument acts as
 276 graph template identifier. There is the possibility to define the pnp template name as custom attribute
 277 and use that inside the formatting templates as `SERVICECHECKCOMMAND` for instance.
 278
 279 Example for services:
 280
 281     # vim /etc/icinga2/features-enabled/perfdata.conf
 282
 283     service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$$pnp_check_arg1$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
 284
 285     # vim /etc/icinga2/conf.d/services.conf
 286
 287     template Service "pnp-svc" {
 288       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 289       vars.pnp_check_arg1 = ""
 290     }
 291
 292     apply Service "nrpe-check" {
 293       import "pnp-svc"
 294       check_command = nrpe
 295       vars.nrpe_command = "check_disk"
 296
 297       vars.pnp_check_arg1 = "!$nrpe_command$"
 298     }
 299
 300 If there are warnings about unresolved macros make sure to specify a default value for `vars.pnp_check_arg1` inside the
 301
 302 In PNP, the custom template for nrpe is then defined in `/etc/pnp4nagios/custom/nrpe.cfg`
 303 and the additional command arg string will be seen in the xml too for other templates.