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