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
 407 > Elasticsearch 5.6.7 and 6.3.1.
 408
 409
 410
 411 Enable the feature and restart Icinga 2.
 412
 413 ```
 414 # icinga2 feature enable elasticsearch
 415 ```
 416
 417 The default configuration expects an Elasticsearch instance running on `localhost` on port `9200
 418  and writes to an index called `icinga2`.
 419
 420 More configuration details can be found [here](09-object-types.md#objecttype-elasticsearchwriter).
 421
 422 #### Current Elasticsearch Schema <a id="elastic-writer-schema"></a>
 423
 424 The following event types are written to Elasticsearch:
 425
 426 * icinga2.event.checkresult
 427 * icinga2.event.statechange
 428 * icinga2.event.notification
 429
 430 Performance data metrics must be explicitly enabled with the `enable_send_perfdata`
 431 attribute.
 432
 433 Metric values are stored like this:
 434
 435     check_result.perfdata.<perfdata-label>.value
 436
 437 The following characters are escaped in perfdata labels:
 438
 439   Character   | Escaped character
 440   ------------|--------------------------
 441   whitespace  | _
 442   \           | _
 443   /           | _
 444   ::          | .
 445
 446 Note that perfdata labels may contain dots (`.`) allowing to
 447 add more subsequent levels inside the tree.
 448 `::` adds support for [multi performance labels](http://my-plugin.de/wiki/projects/check_multi/configuration/performance)
 449 and is therefore replaced by `.`.
 450
 451 Icinga 2 automatically adds the following threshold metrics
 452 if existing:
 453
 454     check_result.perfdata.<perfdata-label>.min
 455     check_result.perfdata.<perfdata-label>.max
 456     check_result.perfdata.<perfdata-label>.warn
 457     check_result.perfdata.<perfdata-label>.crit
 458
 459 ### Graylog Integration <a id="graylog-integration"></a>
 460
 461 #### GELF Writer <a id="gelfwriter"></a>
 462
 463 The `Graylog Extended Log Format` (short: [GELF](http://docs.graylog.org/en/latest/pages/gelf.html))
 464 can be used to send application logs directly to a TCP socket.
 465
 466 While it has been specified by the [Graylog](https://www.graylog.org) project as their
 467 [input resource standard](http://docs.graylog.org/en/latest/pages/sending_data.html), other tools such as
 468 [Logstash](https://www.elastic.co/products/logstash) also support `GELF` as
 469 [input type](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-gelf.html).
 470
 471 You can enable the feature using
 472
 473     # icinga2 feature enable gelf
 474
 475 By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`.
 476 The default `source`  attribute is set to `icinga2`. You can customize that for your needs if required.
 477
 478 Currently these events are processed:
 479 * Check results
 480 * State changes
 481 * Notifications
 482
 483
 484 ### OpenTSDB Writer <a id="opentsdb-writer"></a>
 485
 486 While there are some OpenTSDB collector scripts and daemons like tcollector available for
 487 Icinga 1.x it's more reasonable to directly process the check and plugin performance
 488 in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
 489 write them to the defined TSDB TCP socket.
 490
 491 You can enable the feature using
 492
 493     # icinga2 feature enable opentsdb
 494
 495 By default the `OpenTsdbWriter` object expects the TSD to listen at
 496 `127.0.0.1` on port `4242`.
 497
 498 The current naming schema is
 499
 500     icinga.host.<metricname>
 501     icinga.service.<servicename>.<metricname>
 502
 503 for host and service checks. The tag host is always applied.
 504
 505 To make sure Icinga 2 writes a valid metric into OpenTSDB some characters are replaced
 506 with `_` in the target name:
 507
 508     \  (and space)
 509
 510 The resulting name in OpenTSDB might look like:
 511
 512     www-01 / http-cert / response time
 513     icinga.http_cert.response_time
 514
 515 In addition to the performance data retrieved from the check plugin, Icinga 2 sends
 516 internal check statistic data to OpenTSDB:
 517
 518   metric             | description
 519   -------------------|------------------------------------------
 520   current_attempt    | current check attempt
 521   max_check_attempts | maximum check attempts until the hard state is reached
 522   reachable          | checked object is reachable
 523   downtime_depth     | number of downtimes this object is in
 524   acknowledgement    | whether the object is acknowledged or not
 525   execution_time     | check execution time
 526   latency            | check latency
 527   state              | current state of the checked object
 528   state_type         | 0=SOFT, 1=HARD state
 529
 530 While reachable, state and state_type are metrics for the host or service the
 531 other metrics follow the current naming schema
 532
 533     icinga.check.<metricname>
 534
 535 with the following tags
 536
 537   tag     | description
 538   --------|------------------------------------------
 539   type    | the check type, one of [host, service]
 540   host    | hostname, the check ran on
 541   service | the service name (if type=service)
 542
 543 > **Note**
 544 >
 545 > You might want to set the tsd.core.auto_create_metrics setting to `true`
 546 > in your opentsdb.conf configuration file.
 547
 548
 549 ## Livestatus <a id="setting-up-livestatus"></a>
 550
 551 The [MK Livestatus](https://mathias-kettner.de/checkmk_livestatus.html) project
 552 implements a query protocol that lets users query their Icinga instance for
 553 status information. It can also be used to send commands.
 554
 555 The Livestatus component that is distributed as part of Icinga 2 is a
 556 re-implementation of the Livestatus protocol which is compatible with MK
 557 Livestatus.
 558
 559 > **Tip**
 560 >
 561 > Only install the Livestatus feature if your web interface or addon requires
 562 > you to do so.
 563 > [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2) does not need
 564 > Livestatus.
 565
 566 Details on the available tables and attributes with Icinga 2 can be found
 567 in the [Livestatus Schema](24-appendix.md#schema-livestatus) section.
 568
 569 You can enable Livestatus using icinga2 feature enable:
 570
 571     # icinga2 feature enable livestatus
 572
 573 After that you will have to restart Icinga 2:
 574
 575     # systemctl restart icinga2
 576
 577 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
 578
 579 In order for queries and commands to work you will need to add your query user
 580 (e.g. your web server) to the `icingacmd` group:
 581
 582     # usermod -a -G icingacmd www-data
 583
 584 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
 585 `nagios` if you're using Debian.
 586
 587 Change `www-data` to the user you're using to run queries.
 588
 589 In order to use the historical tables provided by the livestatus feature (for example, the
 590 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
 591 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
 592 `compat_log_path` configuration attribute.
 593
 594     # icinga2 feature enable compatlog
 595
 596
 597 ### Livestatus Sockets <a id="livestatus-sockets"></a>
 598
 599 Other to the Icinga 1.x Addon, Icinga 2 supports two socket types
 600
 601 * Unix socket (default)
 602 * TCP socket
 603
 604 Details on the configuration can be found in the [LivestatusListener](09-object-types.md#objecttype-livestatuslistener)
 605 object configuration.
 606
 607 ### Livestatus GET Queries <a id="livestatus-get-queries"></a>
 608
 609 > **Note**
 610 >
 611 > All Livestatus queries require an additional empty line as query end identifier.
 612 > The `nc` tool (`netcat`) provides the `-U` parameter to communicate using
 613 > a unix socket.
 614
 615 There also is a Perl module available in CPAN for accessing the Livestatus socket
 616 programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/)
 617
 618
 619 Example using the unix socket:
 620
 621     # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus
 622
 623 Example using the tcp socket listening on port `6558`:
 624
 625     # echo -e 'GET services\n' | netcat 127.0.0.1 6558
 626
 627     # cat servicegroups <<EOF
 628     GET servicegroups
 629
 630     EOF
 631
 632     (cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
 633
 634
 635 ### Livestatus COMMAND Queries <a id="livestatus-command-queries"></a>
 636
 637 A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail)
 638
 639     $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
 640
 641
 642 ### Livestatus Filters <a id="livestatus-filters"></a>
 643
 644 and, or, negate
 645
 646   Operator  | Negate   | Description
 647   ----------|----------|-------------
 648    =        | !=       | Equality
 649    ~        | !~       | Regex match
 650    =~       | !=~      | Equality ignoring case
 651    ~~       | !~~      | Regex ignoring case
 652    <        |          | Less than
 653    >        |          | Greater than
 654    <=       |          | Less than or equal
 655    >=       |          | Greater than or equal
 656
 657
 658 ### Livestatus Stats <a id="livestatus-stats"></a>
 659
 660 Schema: "Stats: aggregatefunction aggregateattribute"
 661
 662   Aggregate Function | Description
 663   -------------------|--------------
 664   sum                | &nbsp;
 665   min                | &nbsp;
 666   max                | &nbsp;
 667   avg                | sum / count
 668   std                | standard deviation
 669   suminv             | sum (1 / value)
 670   avginv             | suminv / count
 671   count              | ordinary default for any stats query if not aggregate function defined
 672
 673 Example:
 674
 675     GET hosts
 676     Filter: has_been_checked = 1
 677     Filter: check_type = 0
 678     Stats: sum execution_time
 679     Stats: sum latency
 680     Stats: sum percent_state_change
 681     Stats: min execution_time
 682     Stats: min latency
 683     Stats: min percent_state_change
 684     Stats: max execution_time
 685     Stats: max latency
 686     Stats: max percent_state_change
 687     OutputFormat: json
 688     ResponseHeader: fixed16
 689
 690 ### Livestatus Output <a id="livestatus-output"></a>
 691
 692 * CSV
 693
 694 CSV output uses two levels of array separators: The members array separator
 695 is a comma (1st level) while extra info and host|service relation separator
 696 is a pipe (2nd level).
 697
 698 Separators can be set using ASCII codes like:
 699
 700     Separators: 10 59 44 124
 701
 702 * JSON
 703
 704 Default separators.
 705
 706 ### Livestatus Error Codes <a id="livestatus-error-codes"></a>
 707
 708   Code      | Description
 709   ----------|--------------
 710   200       | OK
 711   404       | Table does not exist
 712   452       | Exception on query
 713
 714 ### Livestatus Tables <a id="livestatus-tables"></a>
 715
 716   Table         | Join      |Description
 717   --------------|-----------|----------------------------
 718   hosts         | &nbsp;    | host config and status attributes, services counter
 719   hostgroups    | &nbsp;    | hostgroup config, status attributes and host/service counters
 720   services      | hosts     | service config and status attributes
 721   servicegroups | &nbsp;    | servicegroup config, status attributes and service counters
 722   contacts      | &nbsp;    | contact config and status attributes
 723   contactgroups | &nbsp;    | contact config, members
 724   commands      | &nbsp;    | command name and line
 725   status        | &nbsp;    | programstatus, config and stats
 726   comments      | services  | status attributes
 727   downtimes     | services  | status attributes
 728   timeperiods   | &nbsp;    | name and is inside flag
 729   endpoints     | &nbsp;    | config and status attributes
 730   log           | services, hosts, contacts, commands | parses [compatlog](09-object-types.md#objecttype-compatlogger) and shows log attributes
 731   statehist     | hosts, services | parses [compatlog](09-object-types.md#objecttype-compatlogger) and aggregates state change attributes
 732   hostsbygroup  | hostgroups | host attributes grouped by hostgroup and its attributes
 733   servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes
 734   servicesbyhostgroup  | hostgroups | service attributes grouped by hostgroup and its attributes
 735
 736 The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
 737
 738 A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](24-appendix.md#schema-livestatus).
 739
 740
 741 ## Status Data Files <a id="status-data"></a>
 742
 743 > **Note**
 744 >
 745 > This feature is DEPRECATED and will be removed in Icinga 2 v2.11.
 746
 747 Icinga 1.x writes object configuration data and status data in a cyclic
 748 interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
 749 the `StatusDataWriter` object which dumps all configuration objects and
 750 status updates in a regular interval.
 751
 752     # icinga2 feature enable statusdata
 753
 754 If you are not using any web interface or addon which uses these files,
 755 you can safely disable this feature.
 756
 757 ## Compat Log Files <a id="compat-logging"></a>
 758
 759 > **Note**
 760 >
 761 > This feature is DEPRECATED and will be removed in Icinga 2 v2.11.
 762
 763 The Icinga 1.x log format is considered being the `Compat Log`
 764 in Icinga 2 provided with the `CompatLogger` object.
 765
 766 These logs are used for informational representation in
 767 external web interfaces parsing the logs, but also to generate
 768 SLA reports and trends.
 769 The [Livestatus](14-features.md#setting-up-livestatus) feature uses these logs
 770 for answering queries to historical tables.
 771
 772 The `CompatLogger` object can be enabled with
 773
 774     # icinga2 feature enable compatlog
 775
 776 By default, the Icinga 1.x log file called `icinga.log` is located
 777 in `/var/log/icinga2/compat`. Rotated log files are moved into
 778 `var/log/icinga2/compat/archives`.
 779
 780 ## Check Result Files <a id="check-result-files"></a>
 781
 782 > **Note**
 783 >
 784 > This feature is DEPRECATED and will be removed in Icinga 2 v2.11.
 785
 786 Icinga 1.x writes its check result files to a temporary spool directory
 787 where they are processed in a regular interval.
 788 While this is extremely inefficient in performance regards it has been
 789 rendered useful for passing passive check results directly into Icinga 1.x
 790 skipping the external command pipe.
 791
 792 Several clustered/distributed environments and check-aggregation addons
 793 use that method. In order to support step-by-step migration of these
 794 environments, Icinga 2 supports the `CheckResultReader` object.
 795
 796 There is no feature configuration available, but it must be defined
 797 on-demand in your Icinga 2 objects configuration.
 798
 799     object CheckResultReader "reader" {
 800       spool_dir = "/data/check-results"
 801     }
 802