Eric Stanley and Andy Brist's presentation on API and Nagios. The presentation was given during the Nagios World Conference North America held Sept 20-Oct 2nd, 2013 in Saint Paul, MN. For more information on the conference (including photos and videos), visit: http://go.nagios.com/nwcna

1. APIs and Nagios
Eric Stanley & Andy Brist
estanley@nagios.com & abrist@nagios.com

2. 2
Why?

3. 3
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

4. 4
Similar Data, Different Methods
Nagios Core APIs
objects.cache / status.dat
Core CGIs
Nagios XI APIs
Backend XML API
PHP content GETs
New Nagios Core APIs
New Core 4 Query Handler
New JSON Core CGI

5. Legacy Nagios
Core APIs

6. 6
Nagios Core Object and Status Files

7. 7
/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 = “nn”

8. 8
/usr/local/nagios/var/objects.cache
grep { /usr/local/nagios/var/objects.cache|uniq
define timeperiod {
define command {
define contactgroup {
define hostgroup {
define servicegroup {
define contact {
define host {
define service {
define escalation {

9. 9
/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 = “nn”

10. 10
/usr/local/nagios/var/status.dat
grep { /usr/local/nagios/var/status.dat|uniq
info {
programstatus {
hoststatus {
servicestatus {
contactstatus {
hostcomment {
servicecomment {
hostdowntime {
servicedowntime {

11. 11
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
}

12. 12
Parsing
awk 'BEGIN { FS="n"; RS="nn" } /'"$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.

13. 13
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!)

14. 14
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

15. 15
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

16. 16
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.

17. 17
Creating GET Queries
General format:
http://<ip>/nagios/cgi-bin/<cgi>?
<selector>=<value>&<selector>=<value>&<etc>
For example: http://<server>/nagios/cgi-bin/status.cgi?
host=gentoo
This will display the status information for the host "gentoo"
Another: http://<server>/nagios/cgi-bin/extinfo.cgi?
type=2&host=gentoo&service=Load
This will display extended information for the service "Load", on
the host "gentoo".

18. 18
status.cgi Selectors
http://<ip>/nagios/cgi-bin/status.cgi?
&hostgroup=<hostgroup> / all
&host=<host> / all
&style=
hostdetail
servicedetail
detail
overview
summary
grid

19. 19
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://<ip>/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

20. 20
Sample HTML local jQuery .load()
<html>
<head>
<script src="https://code.jquery.com/jquery-2.0.3.min.js"></script>
</head>
<body>
<div id='result'></div>
<script>
$('#result').load('/nagios/cgi-bin/status.cgi?hostgroup=all&style=hostdetail');
</script>
</body>
Can use jquery to load directly into a <div>. Can only be used when served
from the nagios server due to cross-domain restrictions.

21. 21
Sample HTML for Cross-site
<html>
<body>
<iframe style="width:800px;height:400px;"
src="https://<username>:<password>@<ip>/nagios/cgi-
bin/status.cgi?hostgroup=all&style=hostdetail'"></iframe>
</body>
Need to use iframe due to cross-domain origin restrictions.

22. 22
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 <div> or <iframe>

23. 23
Cons of Core CGIs
Restrictive formatting:
Mostly tables
Only outputs HTML
Output includes summaries and other tables
No HTML id tags = difficult to scrape

24. Nagios XI APIs

25. 25
Nagios XI APIs
XML Backend GETs
Commands
Selectors / values
Logical operators
Direct URLs
GET URLs for PHP content
status.php examples
Ticket IDs and passwordless GETs

26. 26
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)

27. 27
XI - Constructing a URL GET Request
http://<ip>/nagiosxi/backend/?
cmd=<cmd>&<selector>=<value>&<selector>=<value>&<
etc>
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

28. 28
XI XML Backend - Command List
gethoststatus
getservicestatus
gethosts
getservices
getcomments
getprogramstatus
getusers
getparenthosts
getcontacts
gethostgroups
gethostgroupmembers
getservicegroupmembers
getcustomhostvariablestatus
getstatehistory
getnotifications

29. 29
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.

30. 30
Logical Operators <lo>
Used for further limiting matching values for selectors
Format: ?cmd=<cmd>&<selector>=<lo>:<value>
Examples:
?cmd=gethosts&current_state=ne:0
This 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:2
Returns all "Ping" services with an execution time
greater than 2 seconds (gt accepts floats as well)

31. 31
Logical Operators And String Matches
ne Not Equal lke Like (string ending)
lt Less Than nlke Like (string ending)
lte Less Than or Equal lk Like (mid string)
gt Greater Than lkm Like (mid string)
gte Greater Than or Equal in In
lks Like (string beginning) nin Not In
nlks Not Like (string beginning) eq Equals (default)

32. 32
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.

33. 33
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.

34. 34
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

35. 35
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://<ip>/nagiosxi/includes/components/xicore/<page>.php

36. 36
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=<view>&<selector>

37. 37
XICore – status.php
.../components/xicore/status.php?show=process

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

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

40. 40
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.

41. 41
XI URLS - Ticket ID
Format: ...&username=<user>&ticket=<ticket_id>
Example:
http://<ip>/nagiosxi/backend/?
cmd=gethosts&username=nagiosadmin&ticket=f438720dn934d

42. Query Handler

43. 43
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

44. 44
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

45. 45
Query Handler - Interface
Simple Protocol
<handler> [<command> [<parameters>]]0
Interface Tool
contrib/nagios-qh.rb (Dan Wittenberg)
Demo
More Information: make dox

46. JSON CGIs

47. 47
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

48. 48
JSON CGIs – Current CGIs
objectjson.cgi – static object information
statusjson.cgi – dynamic object information
archivejson.cgi – historical information

49. 49
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 selectors
Selectors are ANDed together
All CGIs support 'help' query

50. 50
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 queries
hostcount, servicegrouplist, commandcount,
timeperiodlist, etc.
Named objects have individual object queries
excludes host/service
dependencies/escalations

51. 51
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)

52. 52
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

53. 53
JSON CGIs – Output Format
format_version – indicates format of following
data
Integer value
Currently 0 indicating no guarantee of stability

54. 54
JSON CGIs – Output Format (cont'd)
results – general results of query
query_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)

55. 55
JSON CGIs – Output Format (cont'd)
data – data that resulted from the query
selectors – 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

56. 56
JSON CGIs – Tools
JSON Query Generator
Javascript tools
Parses help
Executes query and displays URL
Demo

57. 57
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

58. 58
Nagios APIs - Questions
Questions?