granicus.if.org Git - icinga2/blob - doc/9-livestatus.md

   1 ## <a id="setting-up-livestatus"></a> Livestatus
   2
   3 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
   4 implements a query protocol that lets users query their Icinga instance for
   5 status information. It can also be used to send commands.
   6
   7 > **Tip**
   8 >
   9 > Only install the Livestatus feature if your web interface or addon requires
  10 > you to do so (for example, [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2)).
  11 > [Icinga Classic UI](8-alternative-frontends.md#setting-up-icinga-classic-ui) and [Icinga Web](8-alternative-frontends.md#setting-up-icinga-web)
  12 > do not use Livestatus as backend.
  13
  14 The Livestatus component that is distributed as part of Icinga 2 is a
  15 re-implementation of the Livestatus protocol which is compatible with MK
  16 Livestatus.
  17
  18 Details on the available tables and attributes with Icinga 2 can be found
  19 in the [Livestatus Schema](17-appendix.md#schema-livestatus) section.
  20
  21 You can enable Livestatus using icinga2 feature enable:
  22
  23     # icinga2 feature enable livestatus
  24
  25 After that you will have to restart Icinga 2:
  26
  27 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
  28
  29     # service icinga2 restart
  30
  31 RHEL/CentOS 7 and Fedora:
  32
  33     # systemctl restart icinga2
  34
  35 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
  36
  37 In order for queries and commands to work you will need to add your query user
  38 (e.g. your web server) to the `icingacmd` group:
  39
  40     # usermod -a -G icingacmd www-data
  41
  42 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
  43 `nagios` if you're using Debian.
  44
  45 Change `www-data` to the user you're using to run queries.
  46
  47 In order to use the historical tables provided by the livestatus feature (for example, the
  48 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
  49 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
  50 `compat_log_path` configuration attribute.
  51
  52     # icinga2 feature enable compatlog
  53
  54
  55 ### <a id="livestatus-sockets"></a> Livestatus Sockets
  56
  57 Other to the Icinga 1.x Addon, Icinga 2 supports two socket types
  58
  59 * Unix socket (default)
  60 * TCP socket
  61
  62 Details on the configuration can be found in the [LivestatusListener](15-object-types.md#objecttype-livestatuslistener)
  63 object configuration.
  64
  65 ### <a id="livestatus-get-queries"></a> Livestatus GET Queries
  66
  67 > **Note**
  68 >
  69 > All Livestatus queries require an additional empty line as query end identifier.
  70 > The `nc` tool (`netcat`) provides the `-U` parameter to communicate using
  71 > a unix socket.
  72
  73 There also is a Perl module available in CPAN for accessing the Livestatus socket
  74 programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/)
  75
  76
  77 Example using the unix socket:
  78
  79     # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus
  80
  81 Example using the tcp socket listening on port `6558`:
  82
  83     # echo -e 'GET services\n' | netcat 127.0.0.1 6558
  84
  85     # cat servicegroups <<EOF
  86     GET servicegroups
  87
  88     EOF
  89
  90     (cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
  91
  92
  93 ### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries
  94
  95 A list of available external commands and their parameters can be found [here](17-appendix.md#external-commands-list-detail)
  96
  97     $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
  98
  99
 100 ### <a id="livestatus-filters"></a> Livestatus Filters
 101
 102 and, or, negate
 103
 104   Operator  | Negate   | Description
 105   ----------|------------------------
 106    =        | !=       | Equality
 107    ~        | !~       | Regex match
 108    =~       | !=~      | Equality ignoring case
 109    ~~       | !~~      | Regex ignoring case
 110    <        |          | Less than
 111    >        |          | Greater than
 112    <=       |          | Less than or equal
 113    >=       |          | Greater than or equal
 114
 115
 116 ### <a id="livestatus-stats"></a> Livestatus Stats
 117
 118 Schema: "Stats: aggregatefunction aggregateattribute"
 119
 120   Aggregate Function | Description
 121   -------------------|--------------
 122   sum                | &nbsp;
 123   min                | &nbsp;
 124   max                | &nbsp;
 125   avg                | sum / count
 126   std                | standard deviation
 127   suminv             | sum (1 / value)
 128   avginv             | suminv / count
 129   count              | ordinary default for any stats query if not aggregate function defined
 130
 131 Example:
 132
 133     GET hosts
 134     Filter: has_been_checked = 1
 135     Filter: check_type = 0
 136     Stats: sum execution_time
 137     Stats: sum latency
 138     Stats: sum percent_state_change
 139     Stats: min execution_time
 140     Stats: min latency
 141     Stats: min percent_state_change
 142     Stats: max execution_time
 143     Stats: max latency
 144     Stats: max percent_state_change
 145     OutputFormat: json
 146     ResponseHeader: fixed16
 147
 148 ### <a id="livestatus-output"></a> Livestatus Output
 149
 150 * CSV
 151
 152 CSV output uses two levels of array separators: The members array separator
 153 is a comma (1st level) while extra info and host|service relation separator
 154 is a pipe (2nd level).
 155
 156 Separators can be set using ASCII codes like:
 157
 158     Separators: 10 59 44 124
 159
 160 * JSON
 161
 162 Default separators.
 163
 164 ### <a id="livestatus-error-codes"></a> Livestatus Error Codes
 165
 166   Code      | Description
 167   ----------|--------------
 168   200       | OK
 169   404       | Table does not exist
 170   452       | Exception on query
 171
 172 ### <a id="livestatus-tables"></a> Livestatus Tables
 173
 174   Table         | Join      |Description
 175   --------------|-----------|----------------------------
 176   hosts         | &nbsp;    | host config and status attributes, services counter
 177   hostgroups    | &nbsp;    | hostgroup config, status attributes and host/service counters
 178   services      | hosts     | service config and status attributes
 179   servicegroups | &nbsp;    | servicegroup config, status attributes and service counters
 180   contacts      | &nbsp;    | contact config and status attributes
 181   contactgroups | &nbsp;    | contact config, members
 182   commands      | &nbsp;    | command name and line
 183   status        | &nbsp;    | programstatus, config and stats
 184   comments      | services  | status attributes
 185   downtimes     | services  | status attributes
 186   timeperiods   | &nbsp;    | name and is inside flag
 187   endpoints     | &nbsp;    | config and status attributes
 188   log           | services, hosts, contacts, commands | parses [compatlog](15-object-types.md#objecttype-compatlogger) and shows log attributes
 189   statehist     | hosts, services | parses [compatlog](15-object-types.md#objecttype-compatlogger) and aggregates state change attributes
 190
 191 The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
 192
 193 A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](17-appendix.md#schema-livestatus).
 194