## Livestatus The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project implements a query protocol that lets users query their Icinga instance for status information. It can also be used to send commands. > **Tip** > > Only install the Livestatus feature if your web interface or addon requires > you to do so (for example, [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2)). > [Icinga Classic UI](15-alternative-frontends.md#setting-up-icinga-classic-ui) and [Icinga Web](15-alternative-frontends.md#setting-up-icinga-web) > do not use Livestatus as backend. The Livestatus component that is distributed as part of Icinga 2 is a re-implementation of the Livestatus protocol which is compatible with MK Livestatus. Details on the available tables and attributes with Icinga 2 can be found in the [Livestatus Schema](23-appendix.md#schema-livestatus) section. You can enable Livestatus using icinga2 feature enable: # icinga2 feature enable livestatus After that you will have to restart Icinga 2: Debian/Ubuntu, RHEL/CentOS 6 and SUSE: # service icinga2 restart RHEL/CentOS 7 and Fedora: # systemctl restart icinga2 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`. In order for queries and commands to work you will need to add your query user (e.g. your web server) to the `icingacmd` group: # usermod -a -G icingacmd www-data The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to `nagios` if you're using Debian. Change `www-data` to the user you're using to run queries. In order to use the historical tables provided by the livestatus feature (for example, the `log` table) you need to have the `CompatLogger` feature enabled. By default these logs are expected to be in `/var/log/icinga2/compat`. A different path can be set using the `compat_log_path` configuration attribute. # icinga2 feature enable compatlog ### Livestatus Sockets Other to the Icinga 1.x Addon, Icinga 2 supports two socket types * Unix socket (default) * TCP socket Details on the configuration can be found in the [LivestatusListener](6-object-types.md#objecttype-livestatuslistener) object configuration. ### Livestatus GET Queries > **Note** > > All Livestatus queries require an additional empty line as query end identifier. > The `nc` tool (`netcat`) provides the `-U` parameter to communicate using > a unix socket. There also is a Perl module available in CPAN for accessing the Livestatus socket programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/) Example using the unix socket: # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus Example using the tcp socket listening on port `6558`: # echo -e 'GET services\n' | netcat 127.0.0.1 6558 # cat servicegroups < Livestatus COMMAND Queries A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail) $ echo -e 'COMMAND ' | netcat 127.0.0.1 6558 ### Livestatus Filters and, or, negate Operator | Negate | Description ----------|------------------------ = | != | Equality ~ | !~ | Regex match =~ | !=~ | Equality ignoring case ~~ | !~~ | Regex ignoring case < | | Less than > | | Greater than <= | | Less than or equal >= | | Greater than or equal ### Livestatus Stats Schema: "Stats: aggregatefunction aggregateattribute" Aggregate Function | Description -------------------|-------------- sum |   min |   max |   avg | sum / count std | standard deviation suminv | sum (1 / value) avginv | suminv / count count | ordinary default for any stats query if not aggregate function defined Example: GET hosts Filter: has_been_checked = 1 Filter: check_type = 0 Stats: sum execution_time Stats: sum latency Stats: sum percent_state_change Stats: min execution_time Stats: min latency Stats: min percent_state_change Stats: max execution_time Stats: max latency Stats: max percent_state_change OutputFormat: json ResponseHeader: fixed16 ### Livestatus Output * CSV CSV output uses two levels of array separators: The members array separator is a comma (1st level) while extra info and host|service relation separator is a pipe (2nd level). Separators can be set using ASCII codes like: Separators: 10 59 44 124 * JSON Default separators. ### Livestatus Error Codes Code | Description ----------|-------------- 200 | OK 404 | Table does not exist 452 | Exception on query ### Livestatus Tables Table | Join |Description --------------|-----------|---------------------------- hosts |   | host config and status attributes, services counter hostgroups |   | hostgroup config, status attributes and host/service counters services | hosts | service config and status attributes servicegroups |   | servicegroup config, status attributes and service counters contacts |   | contact config and status attributes contactgroups |   | contact config, members commands |   | command name and line status |   | programstatus, config and stats comments | services | status attributes downtimes | services | status attributes timeperiods |   | name and is inside flag endpoints |   | config and status attributes log | services, hosts, contacts, commands | parses [compatlog](6-object-types.md#objecttype-compatlogger) and shows log attributes statehist | hosts, services | parses [compatlog](6-object-types.md#objecttype-compatlogger) and aggregates state change attributes hostsbygroup | hostgroups | host attributes grouped by hostgroup and its attributes servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes servicesbyhostgroup | hostgroups | service attributes grouped by hostgroup and its attributes The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects. A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus).