Name

Nagira -- Nagios RESTful API

Version {include:file:version.txt}

Description

Light-weight web services API for fetching status of Nagios application objects:

• Objects file: hosts, services, contacts, (host|service|contact)groups, escalations, etc.

• Status file: hoststatus, servicestatus, etc.

Source Code

Source code available from Github https://github.com/dmytro/nagira

Installation

See {file:INSTALL.rdoc}

Usage

1. Run Sinatra application bundle exec ./nagira.rb
2. Use HTTP client to get information:

   curl http://localhost:4567/objects/contact/list
   
   curl http://localhost:4567/status/list

or to send check result to Nagios:

curl -X PUT -H "Content-type: application/json;" \
    -d @host_check.json http://nagios.example.com:4567/_status/web_server
    

 {
  "status_code":"0",
  "plugin_output" : "ping OK"
 }
 

See more in {file:FEATURES.rdoc}

Documentation

YARD documentation included with the project, run yardoc in project root directory. Generated YARD docs are available at http://dmytro.github.com/nagira/doc

How and why?

Provide simple and consistent way for information exchange with Nagios

1. Provide read-only access to the object configuration and object states by reading Nagios data files: status.dat and objects.cache, and
   • objects.cache file keeps information about Nagios configuration (lists of servers, services, groups etc);
   • status.dat file is file that stores information about current state of the objects (hosts and services) and Nagios process itself;
   • Nagios configuration information is in nagios.cfg file, by reading and parsing this file all other configuration can be obtained.
2. provide check result submission interface (similar to Nagios NSCA and for setting/updating Nagios configuration.

If necessary at a later stages this could be implemented using Nagios' NEB interface, but the disadvantage of the NEB API is that it could block Nagios process and introduce latencies in Nagios.

File parsing obviously takes resources for each single parse, however if application -- Rails, Sinatra or similar -- is able to keep state of the parser, is not a problem. IF application can keep track of file parse times and file modification time it is possible to parse file only if it was changed and infrequently enough.

Road-map blueprint

When implemented API could provide foundation for development of well-defined, modular, distributed Nagios monitoring: distributed Nagios nodes communicating with each other, retrieving status and submitting check results, distributed, load-balanced, fault tolerant configuration.

Web GUI (IMHO weakest part of the Nagios) could be completely de-coupled from Nagios core and is not required to run on the Nagios core host.

First stage

Note: Implemented in version 0.1

Read-only (GET) routes to access lists of monitored objects and states of the objects.

There are examples of various Nagios interfaces: NDOUTILS, IdoUtils, MK_Livestatus. This is an attempt to do similar things using web services API.

Second stage

Note: Implemented starting from v0.2.

Implement NCSA passive checks submission functionality using HTTP(S) web service.

Starting version v0.2 two Nagios external commands implemented PROCESS_HOST_CHECK_RESULT and PROCESS_SERVICE_CHECK_RESULT. This allows submitting passive check results for hosts and services, and implements accordingly functionality NSCA.

Later stages

Use POST/PUT/DELETE HTTP methods to control Nagios - automatically change configuration, control notifications, contacts; in many cases this requires Nagios process restarts/reloads.

There are 157 external commands in Nagios 3, compared to 2 implemented, so this is still far away...

Author

Dmytro Kovalov, [email protected]

2011, Dec, 26th - started

License

MIT, see {file:LICENSE.rdoc}