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

   1 # Icinga 2 Features <a id="icinga2-features"></a>
   2
   3 ## Logging <a id="logging"></a>
   4
   5 Icinga 2 supports three different types of logging:
   6
   7 * File logging
   8 * Syslog (on Linux/UNIX)
   9 * Console logging (`STDOUT` on tty)
  10
  11 You can enable additional loggers using the `icinga2 feature enable`
  12 and `icinga2 feature disable` commands to configure loggers:
  13
  14 Feature  | Description
  15 ---------|------------
  16 debuglog | Debug log (path: `/var/log/icinga2/debug.log`, severity: `debug` or higher)
  17 mainlog  | Main log (path: `/var/log/icinga2/icinga2.log`, severity: `information` or higher)
  18 syslog   | Syslog (severity: `warning` or higher)
  19
  20 By default file the `mainlog` feature is enabled. When running Icinga 2
  21 on a terminal log messages with severity `information` or higher are
  22 written to the console.
  23
  24 Packages will install a configuration file for logrotate on supported
  25 platforms. This configuration ensures that the `icinga2.log`, `error.log` and
  26 `debug.log` files are rotated on a daily basis.
  27
  28 ## DB IDO <a id="db-ido"></a>
  29
  30 The IDO (Icinga Data Output) feature for Icinga 2 takes care of exporting all
  31 configuration and status information into a database. The IDO database is used
  32 by Icinga Web 2 as data backend.
  33
  34 Details on the installation can be found in the [Configuring DB IDO](02-getting-started.md#configuring-db-ido-mysql)
  35 chapter. Details on the configuration can be found in the
  36 [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and
  37 [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection)
  38 object configuration documentation.
  39 The DB IDO feature supports [High Availability](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) in
  40 the Icinga 2 cluster.
  41
  42 ### DB IDO Health <a id="db-ido-health"></a>
  43
  44 If the monitoring health indicator is critical in Icinga Web 2,
  45 you can use the following queries to manually check whether Icinga 2
  46 is actually updating the IDO database.
  47
  48 Icinga 2 writes its current status to the `icinga_programstatus` table
  49 every 10 seconds. The query below checks 60 seconds into the past which is a reasonable
  50 amount of time -- adjust it for your requirements. If the condition is not met,
  51 the query returns an empty result.
  52
  53 > **Tip**
  54 >
  55 > Use [check plugins](05-service-monitoring.md#service-monitoring-plugins) to monitor the backend.
  56
  57 Replace the `default` string with your instance name if different.
  58
  59 Example for MySQL:
  60
  61 ```
  62 # mysql -u root -p icinga -e "SELECT status_update_time FROM icinga_programstatus ps
  63   JOIN icinga_instances i ON ps.instance_id=i.instance_id
  64   WHERE (UNIX_TIMESTAMP(ps.status_update_time) > UNIX_TIMESTAMP(NOW())-60)
  65   AND i.instance_name='default';"
  66
  67 +---------------------+
  68 | status_update_time  |
  69 +---------------------+
  70 | 2014-05-29 14:29:56 |
  71 +---------------------+
  72 ```
  73
  74 Example for PostgreSQL:
  75
  76 ```
  77 # export PGPASSWORD=icinga; psql -U icinga -d icinga -c "SELECT ps.status_update_time FROM icinga_programstatus AS ps
  78   JOIN icinga_instances AS i ON ps.instance_id=i.instance_id
  79   WHERE ((SELECT extract(epoch from status_update_time) FROM icinga_programstatus) > (SELECT extract(epoch from now())-60))
  80   AND i.instance_name='default'";
  81
  82 status_update_time
  83 ------------------------
  84  2014-05-29 15:11:38+02
  85 (1 Zeile)
  86 ```
  87
  88 A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](24-appendix.md#schema-db-ido).
  89
  90 ### DB IDO Cleanup <a id="db-ido-cleanup"></a>
  91
  92 Objects get deactivated when they are deleted from the configuration.
  93 This is visible with the `is_active` column in the `icinga_objects` table.
  94 Therefore all queries need to join this table and add `WHERE is_active=1` as
  95 condition. Deleted objects preserve their history table entries for later SLA
  96 reporting.
  97
  98 Historical data isn't purged by default. You can enable the least
  99 kept data age inside the `cleanup` configuration attribute for the
 100 IDO features [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection)
 101 and [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection).
 102
 103 Example if you prefer to keep notification history for 30 days:
 104
 105 ```
 106   cleanup = {
 107      notifications_age = 30d
 108      contactnotifications_age = 30d
 109   }
 110 ```
 111
 112 The historical tables are populated depending on the data `categories` specified.
 113 Some tables are empty by default.
 114
 115 ### DB IDO Tuning <a id="db-ido-tuning"></a>
 116
 117 As with any application database, there are ways to optimize and tune the database performance.
 118
 119 General tips for performance tuning:
 120
 121 * [MariaDB KB](https://mariadb.com/kb/en/library/optimization-and-tuning/)
 122 * [PostgreSQL Wiki](https://wiki.postgresql.org/wiki/Performance_Optimization)
 123
 124 Re-creation of indexes, changed column values, etc. will increase the database size. Ensure to
 125 add health checks for this, and monitor the trend in your Grafana dashboards.
 126
 127 In order to optimize the tables, there are different approaches. Always keep in mind to have a
 128 current backup and schedule maintenance downtime for these kind of tasks!
 129
 130 MySQL:
 131
 132 ```
 133 mariadb> OPTIMIZE TABLE icinga_statehistory;
 134 ```
 135
 136 > **Important**
 137 >
 138 > Tables might not support optimization at runtime. This can take a **long** time.
 139 >
 140 > `Table does not support optimize, doing recreate + analyze instead`.
 141
 142 If you want to optimize all tables in a specified database, there is a script called `mysqlcheck`.
 143 This also allows to repair broken tables in the case of emergency.
 144
 145 ```
 146 mysqlcheck --optimize icinga
 147 ```
 148
 149 PostgreSQL:
 150
 151 ```
 152 icinga=# vacuum;
 153 VACUUM
 154 ```
 155
 156 > **Note**
 157 >
 158 > Don't use `VACUUM FULL` as this has a severe impact on performance.
 159
 160
 161 ## External Commands <a id="external-commands"></a>
 162
 163 > **Note**
 164 >
 165 > Please use the [REST API](12-icinga2-api.md#icinga2-api) as modern and secure alternative
 166 > for external actions.
 167
 168 Icinga 2 provides an external command pipe for processing commands
 169 triggering specific actions (for example rescheduling a service check
 170 through the web interface).
 171
 172 In order to enable the `ExternalCommandListener` configuration use the
 173 following command and restart Icinga 2 afterwards:
 174
 175     # icinga2 feature enable command
 176
 177 Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
 178 using the default configuration.
 179
 180 Web interfaces and other Icinga addons are able to send commands to
 181 Icinga 2 through the external command pipe, for example for rescheduling
 182 a forced service check:
 183
 184     # /bin/echo "[`date +%s`] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;`date +%s`" >> /var/run/icinga2/cmd/icinga2.cmd
 185
 186     # tail -f /var/log/messages
 187
 188     Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
 189     Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
 190
 191 A list of currently supported external commands can be found [here](24-appendix.md#external-commands-list-detail).
 192
 193 Detailed information on the commands and their required parameters can be found
 194 on the [Icinga 1.x documentation](https://docs.icinga.com/latest/en/extcommands2.html).
 195
 196 ## Performance Data <a id="performance-data"></a>
 197
 198 When a host or service check is executed plugins should provide so-called
 199 `performance data`. Next to that additional check performance data
 200 can be fetched using Icinga 2 runtime macros such as the check latency
 201 or the current service state (or additional custom attributes).
 202
 203 The performance data can be passed to external applications which aggregate and
 204 store them in their backends. These tools usually generate graphs for historical
 205 reporting and trending.
 206
 207 Well-known addons processing Icinga performance data are [PNP4Nagios](13-addons.md#addons-graphing-pnp),
 208 [Graphite](13-addons.md#addons-graphing-graphite) or [OpenTSDB](14-features.md#opentsdb-writer).
 209
 210 ### Writing Performance Data Files <a id="writing-performance-data-files"></a>
 211
 212 PNP4Nagios and Graphios use performance data collector daemons to fetch
 213 the current performance files for their backend updates.
 214
 215 Therefore the Icinga 2 [PerfdataWriter](09-object-types.md#objecttype-perfdatawriter)
 216 feature allows you to define the output template format for host and services helped
 217 with Icinga 2 runtime vars.
 218
 219     host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
 220     service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
 221
 222 The default templates are already provided with the Icinga 2 feature configuration
 223 which can be enabled using
 224
 225     # icinga2 feature enable perfdata
 226
 227 By default all performance data files are rotated in a 15 seconds interval into
 228 the `/var/spool/icinga2/perfdata/` directory as `host-perfdata.<timestamp>` and
 229 `service-perfdata.<timestamp>`.
 230 External collectors need to parse the rotated performance data files and then
 231 remove the processed files.
 232
 233 ### Graphite Carbon Cache Writer <a id="graphite-carbon-cache-writer"></a>
 234
 235 While there are some [Graphite](13-addons.md#addons-graphing-graphite)
 236 collector scripts and daemons like Graphios available for Icinga 1.x it's more
 237 reasonable to directly process the check and plugin performance
 238 in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
 239 write them to the defined Graphite Carbon daemon tcp socket.
 240
 241 You can enable the feature using
 242
 243     # icinga2 feature enable graphite
 244
 245 By default the [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) feature
 246 expects the Graphite Carbon Cache to listen at `127.0.0.1` on TCP port `2003`.
 247
 248 #### Current Graphite Schema <a id="graphite-carbon-cache-writer-schema"></a>
 249
 250 The current naming schema is defined as follows. The [Icinga Web 2 Graphite module](https://github.com/icinga/icingaweb2-module-graphite)
 251 depends on this schema.
 252
 253 The default prefix for hosts and services is configured using
 254 [runtime macros](03-monitoring-basics.md#runtime-macros)like this:
 255
 256     icinga2.$host.name$.host.$host.check_command$
 257     icinga2.$host.name$.services.$service.name$.$service.check_command$
 258
 259 You can customize the prefix name by using the `host_name_template` and
 260 `service_name_template` configuration attributes.
 261
 262 The additional levels will allow fine granular filters and also template
 263 capabilities, e.g. by using the check command `disk` for specific
 264 graph templates in web applications rendering the Graphite data.
 265
 266 The following characters are escaped in prefix labels:
 267
 268   Character     | Escaped character
 269   --------------|--------------------------
 270   whitespace    | _
 271   .             | _
 272   \             | _
 273   /             | _
 274
 275 Metric values are stored like this:
 276
 277     <prefix>.perfdata.<perfdata-label>.value
 278
 279 The following characters are escaped in perfdata labels:
 280
 281   Character     | Escaped character
 282   --------------|--------------------------
 283   whitespace    | _
 284   \             | _
 285   /             | _
 286   ::            | .
 287
 288 Note that perfdata labels may contain dots (`.`) allowing to
 289 add more subsequent levels inside the Graphite tree.
 290 `::` adds support for [multi performance labels](http://my-plugin.de/wiki/projects/check_multi/configuration/performance)
 291 and is therefore replaced by `.`.
 292
 293 By enabling `enable_send_thresholds` Icinga 2 automatically adds the following threshold metrics:
 294
 295     <prefix>.perfdata.<perfdata-label>.min
 296     <prefix>.perfdata.<perfdata-label>.max
 297     <prefix>.perfdata.<perfdata-label>.warn
 298     <prefix>.perfdata.<perfdata-label>.crit
 299
 300 By enabling `enable_send_metadata` Icinga 2 automatically adds the following metadata metrics:
 301
 302     <prefix>.metadata.current_attempt
 303     <prefix>.metadata.downtime_depth
 304     <prefix>.metadata.acknowledgement
 305     <prefix>.metadata.execution_time
 306     <prefix>.metadata.latency
 307     <prefix>.metadata.max_check_attempts
 308     <prefix>.metadata.reachable
 309     <prefix>.metadata.state
 310     <prefix>.metadata.state_type
 311
 312 Metadata metric overview:
 313
 314   metric             | description
 315   -------------------|------------------------------------------
 316   current_attempt    | current check attempt
 317   max_check_attempts | maximum check attempts until the hard state is reached
 318   reachable          | checked object is reachable
 319   downtime_depth     | number of downtimes this object is in
 320   acknowledgement    | whether the object is acknowledged or not
 321   execution_time     | check execution time
 322   latency            | check latency
 323   state              | current state of the checked object
 324   state_type         | 0=SOFT, 1=HARD state
 325
 326 The following example illustrates how to configure the storage schemas for Graphite Carbon
 327 Cache.
 328
 329     [icinga2_default]
 330     # intervals like PNP4Nagios uses them per default
 331     pattern = ^icinga2\.
 332     retentions = 1m:2d,5m:10d,30m:90d,360m:4y
 333
 334
 335 ### InfluxDB Writer <a id="influxdb-writer"></a>
 336
 337 Once there are new metrics available, Icinga 2 will directly write them to the
 338 defined InfluxDB HTTP API.
 339
 340 You can enable the feature using
 341
 342     # icinga2 feature enable influxdb
 343
 344 By default the [InfluxdbWriter](09-object-types.md#objecttype-influxdbwriter) feature
 345 expects the InfluxDB daemon to listen at `127.0.0.1` on port `8086`.
 346
 347 Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
 348 object will automatically add a `metric` tag to each data point. This correlates to the
 349 perfdata label. Fields (value, warn, crit, min, max, unit) are created from data if available
 350 and the configuration allows it.  If a value associated with a tag is not able to be
 351 resolved, it will be dropped and not sent to the target host.
 352
 353 Backslashes are allowed in tag keys, tag values and field keys, however they are also
 354 escape characters when followed by a space or comma, but cannot be escaped themselves.
 355 As a result all trailling slashes in these fields are replaced with an underscore.  This
 356 predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
 357
 358 The database is assumed to exist so this object will make no attempt to create it currently.
 359
 360 If [SELinux](22-selinux.md#selinux) is enabled, it will not allow access for Icinga 2 to InfluxDB until the [boolean](22-selinux.md#selinux-policy-booleans)
 361 `icinga2_can_connect_all` is set to true as InfluxDB is not providing its own policy.
 362
 363 More configuration details can be found [here](09-object-types.md#objecttype-influxdbwriter).
 364
 365 #### Instance Tagging <a id="influxdb-writer-instance-tags"></a>
 366
 367 Consider the following service check:
 368
 369 ```
 370 apply Service "disk" for (disk => attributes in host.vars.disks) {
 371   import "generic-service"
 372   check_command = "disk"
 373   display_name = "Disk " + disk
 374   vars.disk_partitions = disk
 375   assign where host.vars.disks
 376 }
 377 ```
 378
 379 This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
 380 with a host.  What would be useful is to have the data points tagged with the specific instance
 381 for that check.  This would allow you to query time series data for a check on a host and for a
 382 specific instance e.g. /dev/sda.  To do this quite simply add the instance to the service variables:
 383
 384 ```
 385 apply Service "disk" for (disk => attributes in host.vars.disks) {
 386   ...
 387   vars.instance = disk
 388   ...
 389 }
 390 ```
 391
 392 Then modify your writer configuration to add this tag to your data points if the instance variable
 393 is associated with the service:
 394
 395 ```
 396 object InfluxdbWriter "influxdb" {
 397   ...
 398   service_template = {
 399     measurement = "$service.check_command$"
 400     tags = {
 401       hostname = "$host.name$"
 402       service = "$service.name$"
 403       instance = "$service.vars.instance$"
 404     }
 405   }
 406   ...
 407 }
 408 ```
 409
 410 ### Elastic Stack Integration <a id="elastic-stack-integration"></a>
 411
 412 [Icingabeat](https://github.com/icinga/icingabeat) is an Elastic Beat that fetches data
 413 from the Icinga 2 API and sends it either directly to [Elasticsearch](https://www.elastic.co/products/elasticsearch)
 414 or [Logstash](https://www.elastic.co/products/logstash).
 415
 416 More integrations:
 417
 418 * [Logstash output](https://github.com/Icinga/logstash-output-icinga) for the Icinga 2 API.
 419 * [Logstash Grok Pattern](https://github.com/Icinga/logstash-grok-pattern) for Icinga 2 logs.
 420
 421 #### Elasticsearch Writer <a id="elasticsearch-writer"></a>
 422
 423 This feature forwards check results, state changes and notification events
 424 to an [Elasticsearch](https://www.elastic.co/products/elasticsearch) installation over its HTTP API.
 425
 426 The check results include parsed performance data metrics if enabled.
 427
 428 > **Note**
 429 >
 430 > Elasticsearch 5.x or 6.x are required. This feature has been successfully tested with
 431 > Elasticsearch 5.6.7 and 6.3.1.
 432
 433
 434
 435 Enable the feature and restart Icinga 2.
 436
 437 ```
 438 # icinga2 feature enable elasticsearch
 439 ```
 440
 441 The default configuration expects an Elasticsearch instance running on `localhost` on port `9200
 442  and writes to an index called `icinga2`.
 443
 444 More configuration details can be found [here](09-object-types.md#objecttype-elasticsearchwriter).
 445
 446 #### Current Elasticsearch Schema <a id="elastic-writer-schema"></a>
 447
 448 The following event types are written to Elasticsearch:
 449
 450 * icinga2.event.checkresult
 451 * icinga2.event.statechange
 452 * icinga2.event.notification
 453
 454 Performance data metrics must be explicitly enabled with the `enable_send_perfdata`
 455 attribute.
 456
 457 Metric values are stored like this:
 458
 459     check_result.perfdata.<perfdata-label>.value
 460
 461 The following characters are escaped in perfdata labels:
 462
 463   Character   | Escaped character
 464   ------------|--------------------------
 465   whitespace  | _
 466   \           | _
 467   /           | _
 468   ::          | .
 469
 470 Note that perfdata labels may contain dots (`.`) allowing to
 471 add more subsequent levels inside the tree.
 472 `::` adds support for [multi performance labels](http://my-plugin.de/wiki/projects/check_multi/configuration/performance)
 473 and is therefore replaced by `.`.
 474
 475 Icinga 2 automatically adds the following threshold metrics
 476 if existing:
 477
 478     check_result.perfdata.<perfdata-label>.min
 479     check_result.perfdata.<perfdata-label>.max
 480     check_result.perfdata.<perfdata-label>.warn
 481     check_result.perfdata.<perfdata-label>.crit
 482
 483 ### Graylog Integration <a id="graylog-integration"></a>
 484
 485 #### GELF Writer <a id="gelfwriter"></a>
 486
 487 The `Graylog Extended Log Format` (short: [GELF](http://docs.graylog.org/en/latest/pages/gelf.html))
 488 can be used to send application logs directly to a TCP socket.
 489
 490 While it has been specified by the [Graylog](https://www.graylog.org) project as their
 491 [input resource standard](http://docs.graylog.org/en/latest/pages/sending_data.html), other tools such as
 492 [Logstash](https://www.elastic.co/products/logstash) also support `GELF` as
 493 [input type](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-gelf.html).
 494
 495 You can enable the feature using
 496
 497     # icinga2 feature enable gelf
 498
 499 By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`.
 500 The default `source`  attribute is set to `icinga2`. You can customize that for your needs if required.
 501
 502 Currently these events are processed:
 503 * Check results
 504 * State changes
 505 * Notifications
 506
 507
 508 ### OpenTSDB Writer <a id="opentsdb-writer"></a>
 509
 510 While there are some OpenTSDB collector scripts and daemons like tcollector available for
 511 Icinga 1.x it's more reasonable to directly process the check and plugin performance
 512 in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
 513 write them to the defined TSDB TCP socket.
 514
 515 You can enable the feature using
 516
 517     # icinga2 feature enable opentsdb
 518
 519 By default the `OpenTsdbWriter` object expects the TSD to listen at
 520 `127.0.0.1` on port `4242`.
 521
 522 The current naming schema is
 523
 524     icinga.host.<metricname>
 525     icinga.service.<servicename>.<metricname>
 526
 527 for host and service checks. The tag host is always applied.
 528
 529 To make sure Icinga 2 writes a valid metric into OpenTSDB some characters are replaced
 530 with `_` in the target name:
 531
 532     \  (and space)
 533
 534 The resulting name in OpenTSDB might look like:
 535
 536     www-01 / http-cert / response time
 537     icinga.http_cert.response_time
 538
 539 In addition to the performance data retrieved from the check plugin, Icinga 2 sends
 540 internal check statistic data to OpenTSDB:
 541
 542   metric             | description
 543   -------------------|------------------------------------------
 544   current_attempt    | current check attempt
 545   max_check_attempts | maximum check attempts until the hard state is reached
 546   reachable          | checked object is reachable
 547   downtime_depth     | number of downtimes this object is in
 548   acknowledgement    | whether the object is acknowledged or not
 549   execution_time     | check execution time
 550   latency            | check latency
 551   state              | current state of the checked object
 552   state_type         | 0=SOFT, 1=HARD state
 553
 554 While reachable, state and state_type are metrics for the host or service the
 555 other metrics follow the current naming schema
 556
 557     icinga.check.<metricname>
 558
 559 with the following tags
 560
 561   tag     | description
 562   --------|------------------------------------------
 563   type    | the check type, one of [host, service]
 564   host    | hostname, the check ran on
 565   service | the service name (if type=service)
 566
 567 > **Note**
 568 >
 569 > You might want to set the tsd.core.auto_create_metrics setting to `true`
 570 > in your opentsdb.conf configuration file.
 571
 572
 573 ## Livestatus <a id="setting-up-livestatus"></a>
 574
 575 The [MK Livestatus](https://mathias-kettner.de/checkmk_livestatus.html) project
 576 implements a query protocol that lets users query their Icinga instance for
 577 status information. It can also be used to send commands.
 578
 579 The Livestatus component that is distributed as part of Icinga 2 is a
 580 re-implementation of the Livestatus protocol which is compatible with MK
 581 Livestatus.
 582
 583 > **Tip**
 584 >
 585 > Only install the Livestatus feature if your web interface or addon requires
 586 > you to do so.
 587 > [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2) does not need
 588 > Livestatus.
 589
 590 Details on the available tables and attributes with Icinga 2 can be found
 591 in the [Livestatus Schema](24-appendix.md#schema-livestatus) section.
 592
 593 You can enable Livestatus using icinga2 feature enable:
 594
 595     # icinga2 feature enable livestatus
 596
 597 After that you will have to restart Icinga 2:
 598
 599     # systemctl restart icinga2
 600
 601 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
 602
 603 In order for queries and commands to work you will need to add your query user
 604 (e.g. your web server) to the `icingacmd` group:
 605
 606     # usermod -a -G icingacmd www-data
 607
 608 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
 609 `nagios` if you're using Debian.
 610
 611 Change `www-data` to the user you're using to run queries.
 612
 613 In order to use the historical tables provided by the livestatus feature (for example, the
 614 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
 615 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
 616 `compat_log_path` configuration attribute.
 617
 618     # icinga2 feature enable compatlog
 619
 620
 621 ### Livestatus Sockets <a id="livestatus-sockets"></a>
 622
 623 Other to the Icinga 1.x Addon, Icinga 2 supports two socket types
 624
 625 * Unix socket (default)
 626 * TCP socket
 627
 628 Details on the configuration can be found in the [LivestatusListener](09-object-types.md#objecttype-livestatuslistener)
 629 object configuration.
 630
 631 ### Livestatus GET Queries <a id="livestatus-get-queries"></a>
 632
 633 > **Note**
 634 >
 635 > All Livestatus queries require an additional empty line as query end identifier.
 636 > The `nc` tool (`netcat`) provides the `-U` parameter to communicate using
 637 > a unix socket.
 638
 639 There also is a Perl module available in CPAN for accessing the Livestatus socket
 640 programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/)
 641
 642
 643 Example using the unix socket:
 644
 645     # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus
 646
 647 Example using the tcp socket listening on port `6558`:
 648
 649     # echo -e 'GET services\n' | netcat 127.0.0.1 6558
 650
 651     # cat servicegroups <<EOF
 652     GET servicegroups
 653
 654     EOF
 655
 656     (cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
 657
 658
 659 ### Livestatus COMMAND Queries <a id="livestatus-command-queries"></a>
 660
 661 A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail)
 662
 663     $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
 664
 665
 666 ### Livestatus Filters <a id="livestatus-filters"></a>
 667
 668 and, or, negate
 669
 670   Operator  | Negate   | Description
 671   ----------|----------|-------------
 672    =        | !=       | Equality
 673    ~        | !~       | Regex match
 674    =~       | !=~      | Equality ignoring case
 675    ~~       | !~~      | Regex ignoring case
 676    <        |          | Less than
 677    >        |          | Greater than
 678    <=       |          | Less than or equal
 679    >=       |          | Greater than or equal
 680
 681
 682 ### Livestatus Stats <a id="livestatus-stats"></a>
 683
 684 Schema: "Stats: aggregatefunction aggregateattribute"
 685
 686   Aggregate Function | Description
 687   -------------------|--------------
 688   sum                | &nbsp;
 689   min                | &nbsp;
 690   max                | &nbsp;
 691   avg                | sum / count
 692   std                | standard deviation
 693   suminv             | sum (1 / value)
 694   avginv             | suminv / count
 695   count              | ordinary default for any stats query if not aggregate function defined
 696
 697 Example:
 698
 699     GET hosts
 700     Filter: has_been_checked = 1
 701     Filter: check_type = 0
 702     Stats: sum execution_time
 703     Stats: sum latency
 704     Stats: sum percent_state_change
 705     Stats: min execution_time
 706     Stats: min latency
 707     Stats: min percent_state_change
 708     Stats: max execution_time
 709     Stats: max latency
 710     Stats: max percent_state_change
 711     OutputFormat: json
 712     ResponseHeader: fixed16
 713
 714 ### Livestatus Output <a id="livestatus-output"></a>
 715
 716 * CSV
 717
 718 CSV output uses two levels of array separators: The members array separator
 719 is a comma (1st level) while extra info and host|service relation separator
 720 is a pipe (2nd level).
 721
 722 Separators can be set using ASCII codes like:
 723
 724     Separators: 10 59 44 124
 725
 726 * JSON
 727
 728 Default separators.
 729
 730 ### Livestatus Error Codes <a id="livestatus-error-codes"></a>
 731
 732   Code      | Description
 733   ----------|--------------
 734   200       | OK
 735   404       | Table does not exist
 736   452       | Exception on query
 737
 738 ### Livestatus Tables <a id="livestatus-tables"></a>
 739
 740   Table         | Join      |Description
 741   --------------|-----------|----------------------------
 742   hosts         | &nbsp;    | host config and status attributes, services counter
 743   hostgroups    | &nbsp;    | hostgroup config, status attributes and host/service counters
 744   services      | hosts     | service config and status attributes
 745   servicegroups | &nbsp;    | servicegroup config, status attributes and service counters
 746   contacts      | &nbsp;    | contact config and status attributes
 747   contactgroups | &nbsp;    | contact config, members
 748   commands      | &nbsp;    | command name and line
 749   status        | &nbsp;    | programstatus, config and stats
 750   comments      | services  | status attributes
 751   downtimes     | services  | status attributes
 752   timeperiods   | &nbsp;    | name and is inside flag
 753   endpoints     | &nbsp;    | config and status attributes
 754   log           | services, hosts, contacts, commands | parses [compatlog](09-object-types.md#objecttype-compatlogger) and shows log attributes
 755   statehist     | hosts, services | parses [compatlog](09-object-types.md#objecttype-compatlogger) and aggregates state change attributes
 756   hostsbygroup  | hostgroups | host attributes grouped by hostgroup and its attributes
 757   servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes
 758   servicesbyhostgroup  | hostgroups | service attributes grouped by hostgroup and its attributes
 759
 760 The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
 761
 762 A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](24-appendix.md#schema-livestatus).
 763
 764
 765 ## Status Data Files <a id="status-data"></a>
 766
 767 > **Note**
 768 >
 769 > This feature is DEPRECATED and will be removed in Icinga 2 v2.11.
 770
 771 Icinga 1.x writes object configuration data and status data in a cyclic
 772 interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
 773 the `StatusDataWriter` object which dumps all configuration objects and
 774 status updates in a regular interval.
 775
 776     # icinga2 feature enable statusdata
 777
 778 If you are not using any web interface or addon which uses these files,
 779 you can safely disable this feature.
 780
 781 ## Compat Log Files <a id="compat-logging"></a>
 782
 783 > **Note**
 784 >
 785 > This feature is DEPRECATED and will be removed in Icinga 2 v2.11.
 786
 787 The Icinga 1.x log format is considered being the `Compat Log`
 788 in Icinga 2 provided with the `CompatLogger` object.
 789
 790 These logs are used for informational representation in
 791 external web interfaces parsing the logs, but also to generate
 792 SLA reports and trends.
 793 The [Livestatus](14-features.md#setting-up-livestatus) feature uses these logs
 794 for answering queries to historical tables.
 795
 796 The `CompatLogger` object can be enabled with
 797
 798     # icinga2 feature enable compatlog
 799
 800 By default, the Icinga 1.x log file called `icinga.log` is located
 801 in `/var/log/icinga2/compat`. Rotated log files are moved into
 802 `var/log/icinga2/compat/archives`.
 803
 804 ## Check Result Files <a id="check-result-files"></a>
 805
 806 > **Note**
 807 >
 808 > This feature is DEPRECATED and will be removed in Icinga 2 v2.11.
 809
 810 Icinga 1.x writes its check result files to a temporary spool directory
 811 where they are processed in a regular interval.
 812 While this is extremely inefficient in performance regards it has been
 813 rendered useful for passing passive check results directly into Icinga 1.x
 814 skipping the external command pipe.
 815
 816 Several clustered/distributed environments and check-aggregation addons
 817 use that method. In order to support step-by-step migration of these
 818 environments, Icinga 2 supports the `CheckResultReader` object.
 819
 820 There is no feature configuration available, but it must be defined
 821 on-demand in your Icinga 2 objects configuration.
 822
 823     object CheckResultReader "reader" {
 824       spool_dir = "/data/check-results"
 825     }
 826