1 # <a id="addons-plugins"></a> Icinga 2 Addons and Plugins
3 ## <a id="addons-graphing"></a> Graphing
5 ### <a id="addons-graphing-pnp"></a> PNP
7 [PNP](http://www.pnp4nagios.org) is a graphing addon.
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.
12 Use your distribution's package manager to install the `pnp4nagios` package.
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.
19 Enable performance data writer in icinga 2
21 # icinga2 feature enable perfdata
23 Configure npcd to use the performance data created by Icinga 2:
25 vim /etc/pnp4nagios/npcd.cfg
27 Set `perfdata_spool_dir = /var/spool/icinga2/perfdata` and restart the `npcd` daemon.
29 There's also an Icinga Web 2 module for direct PNP graph integration
30 available at https://exchange.icinga.org/icinga/PNP4Nagios
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).
36 ### <a id="addons-graphing-graphite"></a> Graphite
38 [Graphite](http://graphite.readthedocs.org/en/latest/) is a time-series database
39 storing collected metrics and making them available through restful apis
42 Graphite consists of 3 software components:
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
48 Use the [GraphiteWriter](15-features.md#graphite-carbon-cache-writer) feature
49 for sending real-time metrics from Icinga 2 to Graphite.
51 # icinga2 feature enable graphite
53 There are Graphite addons available for collecting the performance data files too (e.g. `Graphios`).
55 A popular alternative frontend for Graphite is for example [Grafana](http://grafana.org).
57 ### <a id="addons-graphing-influxdb"></a> InfluxDB
59 [InfluxDB](https://influxdb.com) is a time series, metrics, and analytics database.
60 It’s written in Go and has no external dependencies.
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)
66 # icinga2 feature enable graphite
68 A popular frontend for InfluxDB is for example [Grafana](http://grafana.org).
70 ## <a id="addons-visualization"></a> Visualization
72 ### <a id="addons-visualization-reporting"></a> Icinga Reporting
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).
77 ### <a id="addons-visualization-nagvis"></a> NagVis
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).
83 The configuration in nagvis.ini.php should look like this for Livestatus for example:
86 backendtype="mklivestatus"
87 socket="unix:/var/run/icinga2/cmd/livestatus"
89 If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/divetoh/icingaweb2-module-nagvis).
91 ### <a id="addons-visualization-thruk"></a> Thruk
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.
96 ## <a id="log-monitoring"></a> Log Monitoring
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.
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.
106 More details can be found in [this blog post](https://www.icinga.org/2014/12/02/team-icinga-at-osmc-2014/).
108 ## <a id="notification-scripts-interfaces"></a> Notification Scripts and Interfaces
110 There's a variety of resources available, for example different notification scripts such as:
112 * E-Mail ([examples](3-monitoring-basics.md#notifications) provided)
120 Additionally external services can be [integrated with Icinga 2](https://www.icinga.org/icinga/integration/):
122 * [Pagerduty](https://www.icinga.org/partners/pagerduty/)
123 * [VictorOps](https://www.icinga.org/partners/victorops/)
124 * [StackStorm](https://www.icinga.org/partners/stackstorm/)
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).
129 ## <a id="configuration-tools"></a> Configuration Management Tools
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.
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/).
138 These tools are currently in development and require feedback and tests:
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)
144 ## <a id="plugins"></a> Plugins
146 For some services you may need additional 'check plugins' which are not provided
147 by the official Monitoring Plugins project.
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:
152 * [Icinga Exchange](https://exchange.icinga.org)
153 * [Icinga Wiki](https://wiki.icinga.org)
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)
159 # cp check_snmp_int.pl /opt/monitoring/plugins
160 # chmod +x /opt/plugins/check_snmp_int.pl
162 # cat /etc/icinga2/constants.conf
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.
169 const PluginDir = "/usr/lib/nagios/plugins"
170 const CustomPluginDir = "/opt/monitoring/plugins"
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:
175 # su - icinga -s /bin/bash
176 $ /opt/monitoring/plugins/check_snmp_int.pl --help
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.
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.
187 There are the following conventions to follow when adding a new command object definition:
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.
197 Example for a custom `my-snmp-int` check command:
199 object CheckCommand "my-snmp-int" {
200 import "plugin-check-command"
202 command = [ CustomPluginDir + "/check_snmp_int.pl" ]
205 "-H" = "$snmp_address$"
206 "-C" = "$snmp_community$"
211 "-n" = "$snmp_interface$"
213 set_if = "$snmp_perf$"
220 vars.snmp_perf = true
221 vars.snmp_warn = "300,400"
222 vars.snmp_crit = "0,600"
225 Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
227 For further information on your monitoring configuration read the
228 [Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
230 You can find additional plugins at the [Icinga Exchange](https://exchange.icinga.org)
232 More details on the plugins can also be found on the Icinga Wiki at https://wiki.icinga.org
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!
240 ## <a id="plugin-api"></a> Plugin API
242 Currently Icinga 2 supports the native plugin API specification from the `Monitoring Plugins`
245 The `Monitoring Plugin API` is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
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).
251 ## <a id="addon-integration-hints"></a> More Addon Integration Hints
253 ### <a id="addons-graphing-pnp-action-url"></a> PNP Action Url
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).
258 template Service "pnp-hst" {
259 action_url = "/pnp4nagios/graph?host=$HOSTNAME$"
262 template Service "pnp-svc" {
263 action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
266 ### <a id="addons-graphing-pnp-custom-templates"></a> PNP Custom Templates with Icinga 2
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
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)
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.
279 Example for services:
281 # vim /etc/icinga2/features-enabled/perfdata.conf
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$"
285 # vim /etc/icinga2/conf.d/services.conf
287 template Service "pnp-svc" {
288 action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
289 vars.pnp_check_arg1 = ""
292 apply Service "nrpe-check" {
295 vars.nrpe_command = "check_disk"
297 vars.pnp_check_arg1 = "!$nrpe_command$"
300 If there are warnings about unresolved macros make sure to specify a default value for `vars.pnp_check_arg1` inside the
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.