Nagios Conference 2013 - Eric Stanley and Andy Brist - API and Nagios
7 likes37,202 views
The document discusses Nagios APIs and Centralized Monitoring, detailing the various methods and tools for retrieving monitoring data and managing configurations. It covers the structure and content of core object files, CGI scripts, and the new JSON APIs in Nagios Core 4, along with pros and cons of each method. Additionally, it provides guidance on constructing URLs for API requests and implementing them in web applications.
![45
Query Handler - Interface
Simple Protocol
<handler> [<command> [<parameters>]]0
Interface Tool
contrib/nagios-qh.rb (Dan Wittenberg)
Demo
More Information: make dox](https://image.slidesharecdn.com/ericstanleyandandybristapiandnagios-131004134746-phpapp01/85/Nagios-Conference-2013-Eric-Stanley-and-Andy-Brist-API-and-Nagios-45-320.jpg)
Nagios Conference 2013 - Eric Stanley and Andy Brist - API and Nagios
- 1. APIs and Nagios Eric Stanley & Andy Brist [email protected] & [email protected]
- 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
- 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
- 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¤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
- 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>
- 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?