granicus.if.org Git - icinga2/blob - doc/13-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](5-advanced-topics.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](13-addons-plugins.md#addons-graphing-pnp-action-url)
  33 and [graph template names](13-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](5-advanced-topics.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 id="addons-graphing-ingraph"></a> inGraph
  56
  57 [inGraph](https://www.netways.org/projects/ingraph/wiki) requires the ingraph-collector addon
  58 to be configured to point at the perfdata files. Icinga 2's [PerfdataWriter](5-advanced-topics.md#performance-data) will
  59 write to the performance data spool directory.
  60
  61 ## <a id="addons-visualization"></a> Visualization
  62
  63 ### <a id="addons-visualization-reporting"></a> Icinga Reporting
  64
  65 By enabling the DB IDO feature you can use the Icinga Reporting package.
  66
  67 ### <a id="addons-visualization-nagvis"></a> NagVis
  68
  69 By using either Livestatus or DB IDO as a backend you can create your own network maps
  70 based on your monitoring configuration and status data using [NagVis](http://www.nagvis.org).
  71
  72 ### <a id="addons-visualization-thruk"></a> Thruk
  73
  74 [Thruk](http://www.thruk.org) is an alternative web interface which can be used with Icinga 2.
  75
  76 ## <a id="log-monitoring"></a> Log Monitoring
  77
  78 Using Logstash or Graylog in your infrastructure and correlate events with your monitoring
  79 is even simpler these days.
  80
  81 * Use the `GelfWriter` feature to write Icinga 2's check and notification events to Graylog or Logstash.
  82 * Configure the logstash `nagios` output to send passive traps to Icinga 2 using the external command pipe.
  83 * Execute a plugin to check Graylog alert streams.
  84
  85 More details can be found in [this blog post](https://www.icinga.org/2014/12/02/team-icinga-at-osmc-2014/).
  86
  87 ## <a id="notification-scripts-interfaces"></a> Notification Scripts and Interfaces
  88
  89 There's a variety of resources available, be it different notification scripts such as:
  90
  91 * E-Mail ([examples](3-monitoring-basics.md#notifications) provided)
  92 * SMS
  93 * Pager (XMPP, etc.)
  94 * Twitter
  95 * IRC
  96 * Ticket systems
  97 * etc.
  98
  99 Additionally external services can be integrated with Icinga 2:
 100
 101 * [Pagerduty](https://www.pagerduty.com/docs/guides/icinga2-integration-guide/)
 102
 103 More information can be found on the [Icinga Website](https://www.icinga.org)
 104 and the [Icinga Wiki](https://wiki.icinga.org/display/howtos/Home).
 105
 106 ## <a id="configuration-tools"></a> Configuration Management Tools
 107
 108 If you require your favourite configuration tool to export Icinga 2 configuration, please get in
 109 touch with their developers. The Icinga project does not provide a configuration web interface
 110 yet. Follow the [Icinga Blog](https://www.icinga.org/blog/) for updates on this topic.
 111
 112 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
 113 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
 114
 115 These tools are currently in development and require feedback and tests:
 116
 117 * [Ansible Roles](https://github.com/Icinga/icinga2-ansible)
 118 * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
 119 * [Chef Cookbook](https://github.com/Icinga/chef-icinga2)
 120
 121
 122 ## <a id="plugins"></a> Plugins
 123
 124 For some services you may need additional 'check plugins' which are not provided
 125 by the official Monitoring Plugins project.
 126
 127 All existing Nagios or Icinga 1.x plugins work with Icinga 2. Here's a
 128 list of popular community sites which host check plugins:
 129
 130 * [Icinga Exchange](https://exchange.icinga.org)
 131 * [Icinga Wiki](https://wiki.icinga.org)
 132
 133 The recommended way of setting up these plugins is to copy them to a common directory
 134 and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](4-configuring-icinga-2.md#constants-conf)
 135 configuration file:
 136
 137     # cp check_snmp_int.pl /opt/monitoring/plugins
 138     # chmod +x /opt/plugins/check_snmp_int.pl
 139
 140     # cat /etc/icinga2/constants.conf
 141     /**
 142      * This file defines global constants which can be used in
 143      * the other configuration files. At a minimum the
 144      * PluginDir constant should be defined.
 145      */
 146
 147     const PluginDir = "/usr/lib/nagios/plugins"
 148     const CustomPluginDir = "/opt/monitoring/plugins"
 149
 150 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
 151 by trying to run it on the console using whichever user Icinga 2 is running as:
 152
 153     # su - icinga -s /bin/bash
 154     $ /opt/monitoring/plugins/check_snmp_int.pl --help
 155
 156 Additional libraries may be required for some plugins. Please consult the plugin
 157 documentation and/or plugin provided README for installation instructions.
 158 Sometimes plugins contain hard-coded paths to other components. Instead of changing
 159 the plugin it might be easier to create logical links which is (more) update-safe.
 160
 161 Each plugin requires a [CheckCommand](6-object-types.md#objecttype-checkcommand) object in your
 162 configuration which can be used in the [Service](6-object-types.md#objecttype-service) or
 163 [Host](6-object-types.md#objecttype-host) object definition.
 164
 165 There are the following conventions to follow when adding a new command object definition:
 166
 167 * Always import the `plugin-check-command` template
 168 * Use [command-arguments](#) whenever possible. The `command` attribute must be an array
 169 in `[ ... ]` then for shell escaping.
 170 * Define a unique `prefix` for the command's specific command arguments. That way you can safely
 171 set them on host/service level and you'll always know which command they control.
 172 * Use command argument default values, e.g. for thresholds
 173 * Use [advanced conditions](6-object-types.md#objecttype-checkcommand) like `set_if` definitions.
 174
 175 Example for a custom `my-snmp-int` check command:
 176
 177     object CheckCommand "my-snmp-int" {
 178       import "plugin-check-command"
 179
 180       command = [ CustomPluginDir + "/check_snmp_int.pl" ]
 181
 182       arguments = {
 183         "-H" = "$snmp_address$"
 184         "-C" = "$snmp_community$"
 185         "-p" = "$snmp_port$"
 186         "-2" = {
 187           set_if = "$snmp_v2$"
 188         }
 189         "-n" = "$snmp_interface$"
 190         "-f" = {
 191           set_if = "$snmp_perf$"
 192         }
 193         "-w" = "$snmp_warn$"
 194         "-c" = "$snmp_crit$"
 195       }
 196
 197       vars.snmp_v2 = true
 198       vars.snmp_perf = true
 199       vars.snmp_warn = "300,400"
 200       vars.snmp_crit = "0,600"
 201     }
 202
 203 Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
 204
 205 For further information on your monitoring configuration read the
 206 [Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
 207
 208 You can find additional plugins at the [Icinga Exchange](https://exchange.icinga.org)
 209
 210 More details on the plugins can also be found on the Icinga Wiki at https://wiki.icinga.org
 211
 212 > **Tip**
 213 >
 214 > Create the best `CheckCommand` definition there is and send it upstream. More
 215 > 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)
 216 > on the Icinga Wiki. Thank you in advance!
 217
 218 ## <a id="plugin-api"></a> Plugin API
 219
 220 Currently Icinga 2 supports the native plugin API specification from the `Monitoring Plugins`
 221 project.
 222
 223 The `Monitoring Plugin API` is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
 224
 225 There are no output length restrictions using Icinga 2. This is different to the
 226 [Icinga 1.x plugin api definition](http://docs.icinga.org/latest/en/pluginapi.html#outputlengthrestrictions).
 227
 228
 229 ## <a id="addon-integration-hints"></a> More Addon Integration Hints
 230
 231 ### <a id="addons-graphing-pnp-action-url"></a> PNP Action Url
 232
 233 They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require
 234 the action url attribute in its own module).
 235
 236     template Service "pnp-hst" {
 237       action_url = "/pnp4nagios/graph?host=$HOSTNAME$"
 238     }
 239
 240     template Service "pnp-svc" {
 241       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 242     }
 243
 244 ### <a id="addons-graphing-pnp-custom-templates"></a> PNP Custom Templates with Icinga 2
 245
 246 PNP automatically determines the graph template from the check command name (or the argument's name).
 247 This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to
 248 fix this:
 249
 250 * Create a symlink for example from the `templates.dist/check_ping.php` template to the actual check name in Icinga 2 (`templates/ping4.php`)
 251 * Pass the check command name inside the [format template configuration](5-advanced-topics.md#writing-performance-data-files)
 252
 253 The latter becomes difficult with agent based checks like NRPE or SSH where the first command argument acts as
 254 graph template identifier. There is the possibility to define the pnp template name as custom attribute
 255 and use that inside the formatting templates as `SERVICECHECKCOMMAND` for instance.
 256
 257 Example for services:
 258
 259     # vim /etc/icinga2/features-enabled/perfdata.conf
 260
 261     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$"
 262
 263     # vim /etc/icinga2/conf.d/services.conf
 264
 265     template Service "pnp-svc" {
 266       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 267       vars.pnp_check_arg1 = ""
 268     }
 269
 270     apply Service "nrpe-check" {
 271       import "pnp-svc"
 272       check_command = nrpe
 273       vars.nrpe_command = "check_disk"
 274
 275       vars.pnp_check_arg1 = "!$nrpe_command$"
 276     }
 277
 278 If there are warnings about unresolved macros make sure to specify a default value for `vars.pnp_check_arg1` inside the
 279
 280 In PNP, the custom template for nrpe is then defined in `/etc/pnp4nagios/custom/nrpe.cfg`
 281 and the additional command arg string will be seen in the xml too for other templates.