APIs and Nagios

Eric Stanley & Andy Brist

estanley@nagios.com & abrist@nagios.com

Why?

Why Learn the APIs?

Better understanding of the user interfaces

Custom frontend development

Integration into other applications including:Ticketing systems

Third party dashboards

Internal applications

Other monitoring and management frontends

Integrate the nagios check information into other scripted solutions

Troubleshooting and diagnosis

Similar Data, Different Methods

Nagios Core APIsobjects.cache / status.dat

Core CGIs

Nagios XI APIsBackend XML API

PHP content GETs

New Nagios Core APIsNew Core 4 Query Handler

New JSON Core CGI

Legacy Nagios Core APIs

Nagios Core Object and Status Files

/usr/local/nagios/var/objects.cache

Contains core object configuration information

Object data compiled from all configs

Static written out on nagios restart

Does not allow easy cross-indexing or correlations

Field separator = \n

Record (object) separator = \n\n

/usr/local/nagios/var/objects.cache

grep { /usr/local/nagios/var/objects.cache|uniqdefine timeperiod {

define command {

define contactgroup {

define hostgroup {

define servicegroup {

define contact {

define host {

define service {

define escalation {

/usr/local/nagios/var/status.dat

Contains current object status information

Includes states and last/next check times

Includes most of the information in objects.cache

Field separator = \n

Record (object) separator = \n\n

/usr/local/nagios/var/status.dat

grep { /usr/local/nagios/var/status.dat|uniqinfo {

programstatus {

hoststatus {

servicestatus {

contactstatus {

hostcomment {

servicecomment {

hostdowntime {

servicedowntime {

Excerpt of status.dat (contactstatus)

contactstatus { contact_name=nagiosadmin modified_attributes=0 modified_host_attributes=0 modified_service_attributes=0 host_notification_period=nagiosadmin_notification_times service_notification_period=nagiosadmin_notification_times last_host_notification=1368138578 last_service_notification=1368138988 host_notifications_enabled=1 service_notifications_enabled=1 }

Parsing

awk 'BEGIN { FS="\n"; RS="\n\n" } /'"$RECORD"' {/ && /'"$SEARCH"'/ ' $FILE

RECORD=Any object name from either status.dat or objects.cache

contactstatus, hoststatus, programstatus, etc (status.dat)

(define) host, service, contact, etc (objects.cache)

SEARCH=Any object field

current_state, last_state_change, last_update, etc (status.dat)

max_check_attempts, active_checks_enabled, alias, etc (objects.cache)

SEARCH can match a field or a value

There are many ways to parse this file, this is just one example.

Pros of Core Object Files

Can be used by any programming language

Simple and effective

Good for one-offs and quick queries

Great for those comfortable with shell based parsing

Provides that good ole unix experience

Impress your coworkers!

Annoy your Management!

Teach your interns! (please!)

Cons of Core Object Files

Flat files can get very large

Requires parsing skills to use (sed/grep/awk) or other scripting languages

Disk based = slow

Does not persist through restart, and is deleted when the nagios service is stopped

No frontend

Multiple object comparisons and correlations can be troublesome

No externally accessible API available

Core CGIs

avail.cgi

cmd.cgi

config.cgi

extinfo.cgi

histogram.cgi

history.cgi

notifications.cgi

outages.cgi

outages-xml.cgi

showlog.cgi

status.cgi

status-json.cgi

statusmap.cgi

statuswml.cgi

statuswrl.cgi

summary.cgi

tac.cgi

tac-xml.cgi

trends.cgi

Investigate the CGIs on Your Own

Most web pages in Nagios Core are CGIs

The best way to learn about a CGI and it's selectors is to:Right click on the link in the interface and open it in a new tab.

The url in the address field will include the full GET including all the selectors necessary to reproduce the page.

This method can be used for just about any website that uses POST/GET variables

Once you have the URL, you can change the selectors as you see fit.

Creating GET Queries

General format:http:///nagios/cgi-bin/?=&=&

For example: http:///nagios/cgi-bin/status.cgi?host=gentooThis will display the status information for the host "gentoo"

Another: http:///nagios/cgi-bin/extinfo.cgi?type=2&host=gentoo&service=LoadThis will display extended information for the service "Load", on the host "gentoo".

status.cgi Selectors

http:///nagios/cgi-bin/status.cgi?

&hostgroup= / all

&host= / all

&style=hostdetail

servicedetail

detail

overview

summary

grid

status.cgi

Nagios uses bitwise operations to quickly calculate what to display for *statustypes.

For example, to display services that are "pending" and "unknown", the value would be:1 + 8 = 9

The final url would be: http:///nagios/cgi-bin/status.cgi?host=all&servicestatustypes=9

&servicestatustypes=1 - pending

2 - ok

4 - warning

8 - unknown

16 - critical

&hoststatustypes=pending - 1

up - 2

down - 4

unreachable - 16

Sample HTML local jQuery .load()

$('#result').load('/nagios/cgi-bin/status.cgi?hostgroup=all&style=hostdetail');

Can use jquery to load directly into a . Can only be used when served from the nagios server due to cross-domain restrictions.

Sample HTML for Cross-site

Need to use iframe due to cross-domain origin restrictions.

Pros of Core CGIs

Universal: every nagios installation (core, XI) will have these CGIs

Easy to build your own dashboards, just dump the ajax response to or

Cons of Core CGIs

Restrictive formatting:Mostly tables

Only outputs HTML

Output includes summaries and other tables

No HTML id tags = difficult to scrape

Nagios XI APIs

Nagios XI APIs

XML Backend GETsCommands

Selectors / values

Logical operators

Direct URLsGET URLs for PHP content

status.php examples

Ticket IDs and passwordless GETs

Nagios XI Backend API

Outputs XML

Accessible through URLs (GET)

Can use ticket IDs to allow rapid response direct urls or passwordless integration into other frontends.

Object views restricted by user/ticket.

Supports multiple selectors and logical operators.

Imports cleanly into excel and other applications supporting XML

Provides a read only interface to the mysql databases: nagios (check & status information)

nagiosql (core configs)

XI - Constructing a URL GET Request

http:///nagiosxi/backend/?cmd=&=&=&

Selector strings are separated by an '&' symbol and have to start with a command

Examples:?cmd=gethoststatus&host_name=localhost

?cmd=getservicestatus&current_state=ne:0

?cmd=getservicestatus&host_name=localhost

?cmd=getservicestatus&name=nlkm:ping

?cmd=getservicestatus&combinedhost

XI XML Backend - Command List

gethoststatus

getservicestatus

gethosts

getservices

getcomments

getprogramstatus

getusers

getparenthosts

getcontacts

gethostgroups

gethostgroupmembers

getservicegroupmembers

getcustomhostvariablestatus

getstatehistory

getnotifications

XI XML Backend - Commands

Every GET must start with a command as its potential return is limited by the selectors.

Properly formatted GETs will return XML data

If you are unsure of the possible selector values for a given command, only use the command without selectors to return the entirety of the XML. From there you can refer to the XML selectors or values to further limit your GET.

Logical Operators

Used for further limiting matching values for selectors

Format: ?cmd=&=:Examples:

?cmd=gethosts&current_state=ne:0This GET will return all hosts whose current state is not equal to '0' (hosts not in an OK state)

?cmd=getservicestatus&name=Ping&execution_time=gt:2Returns all "Ping" services with an execution time greater than 2 seconds (gt accepts floats as well)

Logical Operators And String Matches

neNot EquallkeLike (string ending)

ltLess ThannlkeLike (string ending)

lteLess Than or EquallkLike (mid string)

gtGreater ThanlkmLike (mid string)

gteGreater Than or EqualinIn

lksLike (string beginning)ninNot In

nlksNot Like (string beginning)eqEquals (default)

XI - XML Backend - A Couple of Notes

Remember to URL encode the selector values. If you have a space in the host name, make sure to replace the space with '%20', etc.

You must declare a command first, then append your selectors.

Use 'brevity=3' when possible to reduce mysql load/bandwidth.

Multiple logical operators for separate selectors can really help you zero in on the desired information.

As backend calls usually result in a database query, refrain from calling the API too frequently.

Pros of XI XML Backend

Reasonably quick

Easily importable into excel, etc.

Integrates easily into most web frameworks and third party applications

Enough selectors to really drill down the request

Requests that lack the "brevity" selector will expose all of the XML object fields and values for the command.

Works nicely with ajax loops for near realtime updates.

Cons of XI XML Backend

Certain queries may require sql database lookups

Requires parsing to JSON, etc. for integration into client views

Data is aproximately 33% larger than necessary

Times are only exported in date/time format, not unix time

XICore Direct URLS

Treated much in the same way as the backend XML API. It can be limited by selectors for the view.

Delivers php/html, usually tables.

Great for embedding in other web applications.

Almost every XI page (including selectors) can be directly accessed through a URL

Right click any link and open it in a new tab/window. The address field will now include the full url for the page.

This works for pages with forms as well - just open the first link in a new tab, walk through the options and the final page's URL will include all the selectors in the URL necessary to view that specific page in the future.

http:///nagiosxi/includes/components/xicore/.php

XICore - Status.php Views

process

performance

comments

services

hosts

hostgroups

servicegroups

servicedetail

hostdetail

tac

outages

map

search

http://nagiosxi/includes/components/xicore/status.php?show=&

XICore status.php

.../components/xicore/status.php?show=process

XICore status.php

.../components/xicore/status.php?show=hostgroups&hostgroup=linux-servers&style=overview

XICore status.php

.../components/xicore/status.php?show=servicedetail&host=192.168.5.132&service=CPU+Usage+for+VMHost#tab-perfgraphs

XI URLS - Ticket ID

Ticket IDs allow data to be retrieved as a specified user, without a password

It can be appended to any GET request as a selector (including the backend and direct URLs)

Very useful for integrating with other web frontends or custom web portals

It is highly suggested that a read-only user is created, and its ticket ID used for any external, potentially insecure access scenarios.

XI URLS - Ticket ID

Format: ...&username=&ticket=

Example:http:///nagiosxi/backend/?cmd=gethosts&username=nagiosadmin&ticket=f438720dn934d

Query Handler

Query Handler - Overview

New in Nagios Core 4

Interface to Running Nagios Core Daemon

Query Handlers run in main Nagios thread

Must be compiled into Nagios Core

Uses Unix-domain Socket/usr/local/nagios/var/rw/nagios.qh

Query Handler Existing Handlers

core - provides Nagios Core management and information

wproc - provides worker process registration, management and information

nerd - provides a subscription service to the Nagios Event Radio Dispatcher (NERD)

help - provides help for the query handler

echo - implements a basic query handler that simply echoes back the queries sent to it

Query Handler - Interface

Simple Protocol [ []]\0

Interface Toolcontrib/nagios-qh.rb (Dan Wittenberg)

Demo

More Information: make dox

JSON CGIs

JSON CGIs Design Goals

Provide all information available in current CGIs in JSON format

Place the presentation responsibility on the client

Minimize network traffic

Minimize server load

Perform operations on the server side that are significantly more easily done there

JSON CGIs Current CGIs

objectjson.cgi static object information

statusjson.cgi dynamic object information

archivejson.cgi historical information

JSON CGIs - Interface

Use HTTP GET for passing parameters

Use same authentication as other CGIs

Query parameter used to request type of query

Handful of format options

All other options act as selectorsSelectors are ANDed together

All CGIs support 'help' query

JSON CGIs objectjson.cgi

Configuration information for Nagios objects

Current state for run-time configurable attributes (i.e. active checks enabled)

All object types have count and list querieshostcount, servicegrouplist, commandcount, timeperiodlist, etc.

Named objects have individual object queriesexcludes host/service dependencies/escalations

JSON CGIs statusjson.cgi

Run-time information for Nagios objects

Hosts/Services count, list, object queries

Comments/Downtime count, list queries

Program Status programstatus (all information in program status section of status.dat)

Performance Data performance data (information on Performance Info page, extinfo.cgi?type=4)

JSON CGIs archivejson.cgi

Historical information read from archive logs

Alerts alertcount, alertlist

Notifications notificationcount, notificationlist

State Changes statechangelist (used on trends.cgi and avail.cgi)

Availability availability

JSON CGIs Output Format

format_version indicates format of following dataInteger value

Currently 0 indicating no guarantee of stability

JSON CGIs Output Format (cont'd)

results general results of queryquery_time time server began processing query

program_start time Nagios core was last started

type_code result type code

type_text textual representation of type_code

message details about result (i.e. error message)

JSON CGIs Output Format (cont'd)

data data that resulted from the queryselectors echos selector used to produce data, not necessarily all selectors provided

query results data, eg.timeperiodcount number of timeperiods that meet the selector criteria

host information for requested host

JSON CGIs Tools

JSON Query GeneratorJavascript tools

Parses help

Executes query and displays URL

Demo

JSON CGIs Current Status

Available in json branch from Sourceforge git

Needs some authorization checking

Some selectors not implemented

One known Nagios Core 4 issue

Nagios APIs - Questions

Questions?

Click to edit the outline text format

Second Outline Level

Third Outline Level

Fourth Outline Level

Fifth Outline Level

Sixth Outline Level

Seventh Outline Level

Eighth Outline Level

Ninth Outline Level

Click to edit the title text format

Click to edit the title text format

Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelEighth Outline LevelNinth Outline Level