tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Deprecate Livestatus

This commit is contained in:
Alexander A. Klimov 2020-06-09 11:21:05 +02:00
parent a96403331f
commit 48fe2813da
2 changed files with 214 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/09-object-types.md
View File

@ -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. 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). 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: Examples:
``` ```

413
doc/14-features.md
View File

@ -915,210 +915,6 @@ is running on.
## Livestatus <a id="setting-up-livestatus"></a>
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 <a id="livestatus-sockets"></a>
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 <a id="livestatus-get-queries"></a>
> **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 <<EOF
GET servicegroups
EOF
(cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
```
### Livestatus COMMAND Queries <a id="livestatus-command-queries"></a>
A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail)
```
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
```
### Livestatus Filters <a id="livestatus-filters"></a>
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 <a id="livestatus-stats"></a>
Schema: "Stats: aggregatefunction aggregateattribute"
Aggregate Function | Description
-------------------|--------------
sum | &nbsp;
min | &nbsp;
max | &nbsp;
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 <a id="livestatus-output"></a>
* 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 <a id="livestatus-error-codes"></a>
Code | Description
----------|--------------
200 | OK
404 | Table does not exist
452 | Exception on query
### Livestatus Tables <a id="livestatus-tables"></a>
Table | Join |Description
--------------|-----------|----------------------------
hosts | &nbsp; | host config and status attributes, services counter
hostgroups | &nbsp; | hostgroup config, status attributes and host/service counters
services | hosts | service config and status attributes
servicegroups | &nbsp; | servicegroup config, status attributes and service counters
contacts | &nbsp; | contact config and status attributes
contactgroups | &nbsp; | contact config, members
commands | &nbsp; | command name and line
status | &nbsp; | programstatus, config and stats
comments | services | status attributes
downtimes | services | status attributes
timeperiods | &nbsp; | name and is inside flag
endpoints | &nbsp; | 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 <a id="deprecated-features"></a> ## Deprecated Features <a id="deprecated-features"></a>
@ -1237,3 +1033,212 @@ object CheckResultReader "reader" {
spool_dir = "/data/check-results" spool_dir = "/data/check-results"
} }
``` ```
### Livestatus <a id="setting-up-livestatus"></a>
> **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 <a id="livestatus-sockets"></a>
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 <a id="livestatus-get-queries"></a>
> **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 <<EOF
GET servicegroups
EOF
(cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
```
#### Livestatus COMMAND Queries <a id="livestatus-command-queries"></a>
A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail)
```
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
```
#### Livestatus Filters <a id="livestatus-filters"></a>
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 <a id="livestatus-stats"></a>
Schema: "Stats: aggregatefunction aggregateattribute"
Aggregate Function | Description
-------------------|--------------
sum | &nbsp;
min | &nbsp;
max | &nbsp;
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 <a id="livestatus-output"></a>
* 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 <a id="livestatus-error-codes"></a>
Code | Description
----------|--------------
200 | OK
404 | Table does not exist
452 | Exception on query
#### Livestatus Tables <a id="livestatus-tables"></a>
Table | Join |Description
--------------|-----------|----------------------------
hosts | &nbsp; | host config and status attributes, services counter
hostgroups | &nbsp; | hostgroup config, status attributes and host/service counters
services | hosts | service config and status attributes
servicegroups | &nbsp; | servicegroup config, status attributes and service counters
contacts | &nbsp; | contact config and status attributes
contactgroups | &nbsp; | contact config, members
commands | &nbsp; | command name and line
status | &nbsp; | programstatus, config and stats
comments | services | status attributes
downtimes | services | status attributes
timeperiods | &nbsp; | name and is inside flag
endpoints | &nbsp; | 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).