diff --git a/doc/09-object-types.md b/doc/09-object-types.md index 2c2c6f9cc..ebbf2e546 100644 --- a/doc/09-object-types.md +++ b/doc/09-object-types.md @@ -1661,6 +1661,11 @@ require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature e pointing to the log files using the `compat_log_path` configuration attribute. This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus). +> **Note** +> +> This feature is DEPRECATED and will be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + Examples: ``` diff --git a/doc/14-features.md b/doc/14-features.md index aa7572e3f..dc2262ef6 100644 --- a/doc/14-features.md +++ b/doc/14-features.md @@ -915,210 +915,6 @@ is running on. -## Livestatus - -The [MK Livestatus](https://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. - -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. - -> **Tip** -> -> Only install the Livestatus feature if your web interface or addon requires -> you to do so. -> [Icinga Web 2](02-installation.md#setting-up-icingaweb2) does not need -> Livestatus. - -Details on the available tables and attributes with Icinga 2 can be found -in the [Livestatus Schema](24-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: - -``` -# 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](09-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 < - -A list of available external commands and their parameters can be found [here](24-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](09-object-types.md#objecttype-compatlogger) and shows log attributes - statehist | hosts, services | parses [compatlog](09-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](24-appendix.md#schema-livestatus). - ## Deprecated Features @@ -1237,3 +1033,212 @@ object CheckResultReader "reader" { spool_dir = "/data/check-results" } ``` + +### Livestatus + +> **Note** +> +> This feature is DEPRECATED and will be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + +The [MK Livestatus](https://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. + +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. + +> **Tip** +> +> Only install the Livestatus feature if your web interface or addon requires +> you to do so. +> [Icinga Web 2](02-installation.md#setting-up-icingaweb2) does not need +> Livestatus. + +Details on the available tables and attributes with Icinga 2 can be found +in the [Livestatus Schema](24-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: + +``` +# 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](09-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 < + +A list of available external commands and their parameters can be found [here](24-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](09-object-types.md#objecttype-compatlogger) and shows log attributes + statehist | hosts, services | parses [compatlog](09-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](24-appendix.md#schema-livestatus).