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

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