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
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
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”
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
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".
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
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¤t_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¤t_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
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
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
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