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