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](4-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](12-addons-plugins.md#addons-graphing-pnp-action-url)
  33 and [graph template names](12-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](4-advanced-topics.md#graphite-carbon-cache-writer) feature
  49 for sending real-time metrics from Icinga 2 to Graphite.
  50
  51     # icinga 2 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](4-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="configuration-tools"></a> Configuration Management Tools
  88
  89 If you require your favourite configuration tool to export Icinga 2 configuration, please get in
  90 touch with their developers. The Icinga project does not provide a configuration web interface
  91 yet. Follow the [Icinga Blog](https://www.icinga.org/blog/) for updates on this topic.
  92
  93 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
  94 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
  95
  96 These tools are currently in development and require feedback and tests:
  97
  98 * [Ansible Roles](https://github.com/Icinga/icinga2-ansible)
  99 * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
 100 * [Chef Cookbook](https://github.com/Icinga/chef-icinga2)
 101
 102
 103 ## <a id="plugins"></a> Plugins
 104
 105 For some services you may need additional 'check plugins' which are not provided
 106 by the official Monitoring Plugins project.
 107
 108 All existing Nagios or Icinga 1.x plugins work with Icinga 2. Here's a
 109 list of popular community sites which host check plugins:
 110
 111 * [Icinga Exchange](https://exchange.icinga.org)
 112 * [Icinga Wiki](https://wiki.icinga.org)
 113
 114 The recommended way of setting up these plugins is to copy them to a common directory
 115 and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](5-configuring-icinga-2.md#constants-conf)
 116 configuration file:
 117
 118     # cp check_snmp_int.pl /opt/monitoring/plugins
 119     # chmod +x /opt/plugins/check_snmp_int.pl
 120
 121     # cat /etc/icinga2/constants.conf
 122     /**
 123      * This file defines global constants which can be used in
 124      * the other configuration files. At a minimum the
 125      * PluginDir constant should be defined.
 126      */
 127
 128     const PluginDir = "/usr/lib/nagios/plugins"
 129     const CustomPluginDir = "/opt/monitoring/plugins"
 130
 131 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
 132 by trying to run it on the console using whichever user Icinga 2 is running as:
 133
 134     # su - icinga -s /bin/bash
 135     $ /opt/monitoring/plugins/check_snmp_int.pl --help
 136
 137 Additional libraries may be required for some plugins. Please consult the plugin
 138 documentation and/or plugin provided README for installation instructions.
 139 Sometimes plugins contain hard-coded paths to other components. Instead of changing
 140 the plugin it might be easier to create logical links which is (more) update-safe.
 141
 142 Each plugin requires a [CheckCommand](6-object-types.md#objecttype-checkcommand) object in your
 143 configuration which can be used in the [Service](6-object-types.md#objecttype-service) or
 144 [Host](6-object-types.md#objecttype-host) object definition.
 145
 146 There are the following conventions to follow when adding a new command object definition:
 147
 148 * Always import the `plugin-check-command` template
 149 * Use [command-arguments](#) whenever possible. The `command` attribute must be an array
 150 in `[ ... ]` then for shell escaping.
 151 * Define a unique `prefix` for the command's specific command arguments. That way you can safely
 152 set them on host/service level and you'll always know which command they control.
 153 * Use command argument default values, e.g. for thresholds
 154 * Use [advanced conditions](6-object-types.md#objecttype-checkcommand) like `set_if` definitions.
 155
 156 Example for a custom `my-snmp-int` check command:
 157
 158     object CheckCommand "my-snmp-int" {
 159       import "plugin-check-command"
 160
 161       command = [ CustomPluginDir + "/check_snmp_int.pl" ]
 162
 163       arguments = {
 164         "-H" = "$snmp_address$"
 165         "-C" = "$snmp_community$"
 166         "-p" = "$snmp_port$"
 167         "-2" = {
 168           set_if = "$snmp_v2$"
 169         }
 170         "-n" = "$snmp_interface$"
 171         "-f" = {
 172           set_if = "$snmp_perf$"
 173         }
 174         "-w" = "$snmp_warn$"
 175         "-c" = "$snmp_crit$"
 176       }
 177
 178       vars.snmp_v2 = true
 179       vars.snmp_perf = true
 180       vars.snmp_warn = "300,400"
 181       vars.snmp_crit = "0,600"
 182     }
 183
 184 Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
 185
 186 For further information on your monitoring configuration read the
 187 [Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
 188
 189 You can find additional plugins at the [Icinga Exchange](https://exchange.icinga.org)
 190
 191 More details on the plugins can also be found on the Icinga Wiki at https://wiki.icinga.org
 192
 193 ## <a id="plugin-api"></a> Plugin API
 194
 195 Currently Icinga 2 supports the native plugin API specification from the `Monitoring Plugins`
 196 project.
 197
 198 The `Monitoring Plugin API` is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
 199
 200 There are no output length restrictions using Icinga 2. This is different to the
 201 [Icinga 1.x plugin api definition](http://docs.icinga.org/latest/en/pluginapi.html#outputlengthrestrictions).
 202
 203
 204 ## <a id="addon-integration-hints"></a> More Addon Integration Hints
 205
 206 ### <a id="addons-graphing-pnp-action-url"></a> PNP Action Url
 207
 208 They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require
 209 the action url attribute in its own module).
 210
 211     template Service "pnp-hst" {
 212       action_url = "/pnp4nagios/graph?host=$HOSTNAME$"
 213     }
 214
 215     template Service "pnp-svc" {
 216       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 217     }
 218
 219 ### <a id="addons-graphing-pnp-custom-templates"></a> PNP Custom Templates with Icinga 2
 220
 221 PNP automatically determines the graph template from the check command name (or the argument's name).
 222 This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to
 223 fix this:
 224
 225 * Create a symlink for example from the `templates.dist/check_ping.php` template to the actual check name in Icinga 2 (`templates/ping4.php`)
 226 * Pass the check command name inside the [format template configuration](04-advanced-topics.md#writing-performance-data-files)
 227
 228 The latter becomes difficult with agent based checks like NRPE or SSH where the first command argument acts as
 229 graph template identifier. There is the possibility to define the pnp template name as custom attribute
 230 and use that inside the formatting templates as `SERVICECHECKCOMMAND` for instance.
 231
 232 Example for services:
 233
 234     # vim /etc/icinga2/features-enabled/perfdata.conf
 235
 236     service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.checkcommand$$pnp_check_arg1$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.statetype$"
 237
 238     # vim /etc/icinga2/conf.d/services.conf
 239
 240     template Service "pnp-svc" {
 241       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 242       vars.pnp_check_arg1 = ""
 243     }
 244
 245     apply Service "nrpe-check" {
 246       import "pnp-svc"
 247       check_command = nrpe
 248       vars.nrpe_command = "check_disk"
 249
 250       vars.pnp_check_arg1 = "!$nrpe_command$"
 251     }
 252
 253 If there are warnings about unresolved macros make sure to specify a default value for `vars.pnp_check_arg1` inside the
 254
 255 In PNP, the custom template for nrpe is then defined in `/etc/pnp4nagios/custom/nrpe.cfg`
 256 and the additional command arg string will be seen in the xml too for other templates.