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

   1 # Icinga 2 Addons <a id="addons"></a>
   2
   3 ## Graphing <a id="addons-graphing"></a>
   4
   5 ### Graphite <a id="addons-graphing-graphite"></a>
   6
   7 [Graphite](https://graphite.readthedocs.org/en/latest/) is a time-series database
   8 storing collected metrics and making them available through restful apis
   9 and web interfaces.
  10
  11 Graphite consists of 3 software components:
  12
  13 * carbon -- a Twisted daemon that listens for time-series data
  14 * whisper -- a simple database library for storing time-series data (similar in design to RRD)
  15 * graphite webapp -- a Django webapp that renders graphs on-demand using Cairo
  16
  17 You need to install Graphite first, then proceed with configuring it in Icinga 2.
  18
  19 Use the [GraphiteWriter](14-features.md#graphite-carbon-cache-writer) feature
  20 for sending real-time metrics from Icinga 2 to Graphite.
  21
  22     # icinga2 feature enable graphite
  23
  24 A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org).
  25
  26 Integration in Icinga Web 2 is possible by installing the official [graphite module](https://icinga.com/docs/graphite/latest/).
  27
  28 ![Icinga Web 2 Detail View with Graphite](images/addons/icingaweb2_graphite.png)
  29
  30
  31 ### InfluxDB <a id="addons-graphing-influxdb"></a>
  32
  33 [InfluxDB](https://influxdb.com) is a time series, metrics, and analytics database.
  34 It’s written in Go and has no external dependencies.
  35
  36 Use the [InfluxdbWriter](14-features.md#influxdb-writer) feature
  37 for sending real-time metrics from Icinga 2 to InfluxDB.
  38
  39     # icinga2 feature enable influxdb
  40
  41 A popular frontend for InfluxDB is for example [Grafana](https://grafana.org).
  42
  43 Integration in Icinga Web 2 is possible by installing the community [Grafana module](https://github.com/Mikesch-mp/icingaweb2-module-grafana).
  44
  45 ![Icinga Web 2 Detail View with Grafana](images/addons/icingaweb2_grafana.png)
  46
  47
  48 ### PNP <a id="addons-graphing-pnp"></a>
  49
  50 [PNP](https://www.pnp4nagios.org) is a graphing addon.
  51
  52 [PNP](https://www.pnp4nagios.org) is an addon which adds a graphical representation of the performance data collected
  53 by the monitoring plugins. The data is stored as rrd (round robin database) files.
  54
  55 Use your distribution's package manager to install the `pnp4nagios` package.
  56
  57 If you're planning to use it, configure it to use the
  58 [bulk mode with npcd and npcdmod](https://docs.pnp4nagios.org/pnp-0.6/modes#bulk_mode_with_npcd_and_npcdmod)
  59 in combination with Icinga 2's [PerfdataWriter](14-features.md#performance-data). NPCD collects the performance
  60 data files which Icinga 2 generates.
  61
  62 Enable performance data writer in icinga 2
  63
  64     # icinga2 feature enable perfdata
  65
  66 Configure npcd to use the performance data created by Icinga 2:
  67
  68     vim /etc/pnp4nagios/npcd.cfg
  69
  70 Set `perfdata_spool_dir = /var/spool/icinga2/perfdata` and restart the `npcd` daemon.
  71
  72 There's also an Icinga Web 2 module for direct PNP graph integration
  73 available at [Icinga Exchange](https://exchange.icinga.com/icinga/PNP).
  74
  75 More information on [action_url as attribute](13-addons.md#addons-graphing-pnp-action-url)
  76 and [graph template names](13-addons.md#addons-graphing-pnp-custom-templates).
  77
  78
  79 ## Visualization <a id="addons-visualization"></a>
  80
  81 ### Maps <a id="addons-visualization-maps"></a>
  82
  83 This community module displays host objects as markers on openstreetmap in Icinga Web 2.
  84 It uses the data provided by the monitoring module and as such the [DB IDO](14-features.md#db-ido)
  85 from Icinga 2.
  86
  87 If you configure multiple hosts with the same coordinates, i.e. servers in a datacenter, a clustered view is rendered.
  88
  89 Check the  [Map module docs](https://github.com/nbuchwitz/icingaweb2-module-map) for more details on
  90 installation, configuration and integration.
  91
  92 ![Icinga Web 2 Maps](images/addons/icingaweb2_maps.png)
  93
  94 ### Dashing Dashboard <a id="addons-visualization-dashing-dashboard"></a>
  95
  96 The [Icinga 2 dashboard](https://github.com/dnsmichi/dashing-icinga2) is built
  97 on top of Dashing and uses the [REST API](12-icinga2-api.md#icinga2-api) to visualize what's going
  98 on with your monitoring. It combines several popular widgets and provides development
  99 instructions for your own implementation.
 100
 101 The dashboard also allows to embed the [Icinga Web 2](https://icinga.com/products/icinga-web-2/)
 102 host and service problem lists as Iframe.
 103
 104 ![Dashing dashboard](images/addons/dashing_icinga2.png)
 105
 106 ### Business Process <a id="addons-business-process"></a>
 107
 108 Create top-level views of your applications in a graphical editor.
 109 Rules express dependencies between existing hosts and services and
 110 let you alert on application level. Business processes are displayed
 111 in a tree or list overview and can be added to any dashboard.
 112
 113 ![Icinga Web 2 Business Process](images/addons/icingaweb2_businessprocess.png)
 114
 115 ### NagVis <a id="addons-visualization-nagvis"></a>
 116
 117 By using the [DB IDO](14-features.md#db-ido) feature
 118 you can create your own network maps
 119 based on your monitoring configuration and status data using [NagVis](https://www.nagvis.org).
 120
 121 The configuration in nagvis.ini.php should look like this for Livestatus for example:
 122
 123     [backend_live_1]
 124     backendtype="mklivestatus"
 125     socket="unix:/var/run/icinga2/cmd/livestatus"
 126
 127 If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/Icinga/icingaweb2-module-nagvis).
 128
 129 ### Icinga Reporting <a id="addons-visualization-reporting"></a>
 130
 131 By enabling the [DB IDO](14-features.md#db-ido) feature you can use the
 132 [Icinga Reporting package](https://icinga.com/docs/icinga1/latest/en/reporting.html).
 133
 134 ### Thruk <a id="addons-visualization-thruk"></a>
 135
 136 [Thruk](https://www.thruk.org) is an alternative web interface which can be used with Icinga 2
 137 and the [Livestatus](14-features.md#setting-up-livestatus) feature.
 138
 139 ## Log Monitoring <a id="log-monitoring"></a>
 140
 141 Using [Logstash](https://www.elastic.co/guide/en/logstash/current/introduction.html) or
 142 [Graylog](https://www.graylog.org) in your infrastructure and correlate events with your monitoring
 143 is even simpler these days.
 144
 145 * Use the `GelfWriter` feature to write Icinga 2's check and notification events to Graylog or Logstash.
 146 * Configure the logstash `nagios` output to send passive traps to Icinga 2 using the external command pipe.
 147 * Execute a plugin to check Graylog alert streams.
 148
 149 More details can be found in [this blog post](https://icinga.com/2014/12/02/team-icinga-at-osmc-2014/).
 150
 151 ## Notification Scripts and Interfaces <a id="notification-scripts-interfaces"></a>
 152
 153 There's a variety of resources available, for example different notification scripts such as:
 154
 155 * E-Mail ([examples](03-monitoring-basics.md#alert-notifications) provided)
 156 * SMS
 157 * Pager (XMPP, etc.)
 158 * Twitter
 159 * IRC
 160 * Ticket systems
 161 * etc.
 162
 163 Additionally external services can be [integrated with Icinga 2](https://icinga.com/products/integrations/):
 164
 165 * [Pagerduty](https://icinga.com/products/integrations/pagerduty/)
 166 * [VictorOps](https://icinga.com/products/integrations/victorops/)
 167 * [StackStorm](https://icinga.com/products/integrations/stackstorm/)
 168
 169 More information can be found on the [Icinga Website](https://icinga.com/).
 170
 171 ## Configuration Management Tools <a id="configuration-tools"></a>
 172
 173 If you require your favourite configuration tool to export the Icinga 2 configuration, please get in
 174 touch with their developers. The Icinga project does not provide a configuration web interface
 175 yet. Follow the [Icinga Blog](https://icinga.com/blog/) for updates on this topic.
 176
 177 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc. -- we're happy
 178 to integrate them upstream, so please get in touch with the [Icinga team](https://icinga.com/community/).
 179
 180 These tools are currently in development and require feedback and tests:
 181
 182 * [Ansible Roles](https://github.com/Icinga/icinga2-ansible)
 183 * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
 184 * [Chef Cookbook](https://github.com/Icinga/chef-icinga2)
 185
 186 ## More Addon Integration Hints <a id="addon-integration-hints"></a>
 187
 188 ### PNP Action Url <a id="addons-graphing-pnp-action-url"></a>
 189
 190 They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require
 191 the action url attribute in its own module).
 192
 193     template Host "pnp-hst" {
 194       action_url = "/pnp4nagios/graph?host=$HOSTNAME$"
 195     }
 196
 197     template Service "pnp-svc" {
 198       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 199     }
 200
 201 ### PNP Custom Templates with Icinga 2 <a id="addons-graphing-pnp-custom-templates"></a>
 202
 203 PNP automatically determines the graph template from the check command name (or the argument's name).
 204 This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to
 205 fix this:
 206
 207 * Create a symlink for example from the `templates.dist/check_ping.php` template to the actual check name in Icinga 2 (`templates/ping4.php`)
 208 * Pass the check command name inside the [format template configuration](14-features.md#writing-performance-data-files)
 209
 210 The latter becomes difficult with agent based checks like NRPE or SSH where the first command argument acts as
 211 graph template identifier. There is the possibility to define the pnp template name as custom attribute
 212 and use that inside the formatting templates as `SERVICECHECKCOMMAND` for instance.
 213
 214 Example for services:
 215
 216     # vim /etc/icinga2/features-enabled/perfdata.conf
 217
 218     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$"
 219
 220     # vim /etc/icinga2/conf.d/services.conf
 221
 222     template Service "pnp-svc" {
 223       action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
 224       vars.pnp_check_arg1 = ""
 225     }
 226
 227     apply Service "nrpe-check" {
 228       import "pnp-svc"
 229       check_command = nrpe
 230       vars.nrpe_command = "check_disk"
 231
 232       vars.pnp_check_arg1 = "!$nrpe_command$"
 233     }
 234
 235 If there are warnings about unresolved macros, make sure to specify a default value for `vars.pnp_check_arg1` inside the
 236
 237 In PNP, the custom template for nrpe is then defined in `/etc/pnp4nagios/custom/nrpe.cfg`
 238 and the additional command arg string will be seen in the xml too for other templates.