LivestatusSlave – Webservice for MKLivestatus

MKLivestatus is a Nagios Event Broker (NEB) Module which can be used to extend the core of Nagios. The MKLivestatus module provides access to the live status information kept in the running Nagios process. It serves a unix socket for data exchange with external scripts/addons.

Making Livestatus available on the Network

It is possible to make the Livstatus unix socket (which is only available on the system where Livestatus runs) to remote systems on the network e.g. using xinetd.

Using xinetd the unix socket is served as tcp socket on the network. This tcp/unix sockets can be queried using the most programming languages.

But in many cases it would be better to have an easier way reaching the Livestatus information.

A big benefit could be to have the livestatus socket available via HTTP to make it queryable for example using XMLHttpRequest.

With this idea the LivestatusSlave was born.

What is the LivestatusSlave?

The LivestatusSlave is a so called “webservice” written in PHP. Basically LivestatusSlave is a single PHP script which gets the plain livestatus query from a parameter and returns the livestatus response as array in JSON syntax.

LivestatusSlave does not really care about authentication, authorisation or the syntax of the livestatus query. It is only a small translator between the HTTP client and the Livestatus socket.

Downloading LivestatusSlave

LivestatusSlave is in early developement. A package of livestatus slave can be downloaded here: livestatus-slave-1.1.tar.gz.

There is also a public git repository available which contains the newest sources: mklivestatus-slave.

System Requirements

LivestatusSlave needs a webserver which supports at least PHP 5. The PHP needs suport for json and socket functions. You might need to install additional packages to get those modules.

And you also need a running Nagios with a loaded MKLivestatus NEB module.

Installing LivestatusSlave

Just drop the live.php somewhere on your system where it is reachable via a webserver which supports PHP. For example you could place it in your nagios/share directory.

Then you need to edit the $conf Array in live.php to point to your Livestatus socket path.

Example

I placed the live.php in my nagios/share directory so it is reachable now via:

http://<my-nagios-server>/nagios/live.php

It is very easy to query the LivestatusSlave. Simply open the live.php in your Browser with the following URL:

http://<my-nagios-server>/nagios/live.php?q=GET hosts\nColumns: name state\nFilter: name = www.nagvis.org\n

Now I get the following response:

[[0,"OK"],[["www.nagvis.org",0]]]

More readable and with comments added:

[
  // Header
  [
    // Response Code
    0,
    // Response Message
    "OK"
  ],
  // Body
  [["www.nagvis.org",0]]
]

The response is in JSON format. It is an array where the first element is the header which is an array itselfs and the second element is the response body which may be an array of elements.

The response header is built of two elements. The first element is the response code, the second element is the description of the response, for example an error message.

The response code is 0 on a successful query and different than 0 when a problem occured.