Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
features:nems-api [2018/08/22 16:47]
Robbie Ferguson created
features:nems-api [2019/02/04 11:35] (current)
Line 3: Line 3:
 //​nems-api//​ is a web-based api interface that outputs json data related to your NEMS server. It is lightweight,​ fast, and offers a connection for both internal NEMS features and third-party devices. //​nems-api//​ is a web-based api interface that outputs json data related to your NEMS server. It is lightweight,​ fast, and offers a connection for both internal NEMS features and third-party devices.
  
-====Commands====+//​nems-api//​ will always return either //success: true// or //success: false// to tell you whether a query was successful or not.
  
-  * **https://nems.local/nems-api/hosts** - output all configured hosts +====IP Restrictions==== 
-  * **https://​nems.local/nems-api/​services** - output all configured services + 
-  * **https://​nems.local/nems-api/​downtimes** ​output all scheduled downtimes+By default, access to //nems-api// is limited to the following IP addresses:​ 
 + 
 +  ​127.0.0.1 
 +  ​10.0.0.0 ​10.255.255.255 
 +  * 172.16.0.0 ​172.31.255.255 
 +  * 192.168.0.0 ​192.168.255.255 
 + 
 +If you need to add an outside IP address, please put in a feature request in the Community Forum to add this feature to NEMS-SST. If there is demand for it, it will be added.
  
 ====Secure Certificate==== ====Secure Certificate====
  
-NEMS Linux uses self-signed certificates. In order to pull //​nems-api//​ data you must either ​ignore the certificates via your application, ​or change ​the URL to non-SSL (not recommended).+NEMS Linux uses self-signed certificates. In order to pull //​nems-api//​ data over ssl (ie., https), ​you must ignore the certificates via your application
 + 
 +====Command Examples==== 
 + 
 +All examples in this document assume that the API is available at 
 + 
 +<​code>​http://​nems.local/​nems-api/</​code>​ 
 + 
 +  * **http://​nems.local/​nems-api/​hosts** - output all configured hosts 
 +  * **http://​nems.local/​nems-api/​services** - output all configured services 
 +  * **http://​nems.local/​nems-api/​downtimes** - output all scheduled downtimes 
 +  * **http://​nems.local/​nems-api/​hosts?​Columns=name,state** - output all host names along with their current state 
 + 
 + 
 +===== Response Format ===== 
 + 
 +All responses are in JSON and have the following format: 
 + 
 +<​code>​{"​success":​ <​bool>,​ "​content":​ <​object>​}</​code>​ 
 + 
 +If "​success"​ is true, "​content"​ will contain the requested data. If false, it will contain 
 + 
 +<​code>​{"​code":​ <​int>,​ "​message":​ <​string>​}</​code>​ 
 + 
 +where "​code"​ is the mk-livestatus error code and "​message"​ is a human-readable explanation of the error. 
 + 
 +===== Query interface ===== 
 + 
 +The query interface returns a list of objects in JSON. The available endpoints are the same as the tables available from mk-livestatus itself: 
 + 
 +  * hosts 
 +  * services - Nagios services, joined with all data from hosts 
 +  * hostgroups 
 +  * servicegroups 
 +  * contactgroups 
 +  * servicesbygroup - all services grouped by service groups 
 +  * servicesbyhostgroup - all services grouped by host groups 
 +  * hostsbygroup - all hosts grouped by host groups 
 +  * contacts 
 +  * commands - your defined Nagios commands 
 +  * timeperiods - time period definitions (currently only name and alias) 
 +  * downtimes - all scheduled host and service downtimes, joined with data from hosts and services. 
 +  * comments - all host and service comments 
 +  * log - a transparent access ​to the nagios logfiles 
 +  * status ​general performance and status information. This table contains exactly one dataset. 
 +  * columns - a complete list of all tables and columns available via Livestatus, including descriptions! 
 +  * statehist - sla statistics for hosts and services, joined with data from hosts, services and log. 
 + 
 +To retrieve all records from a table, send a GET request to 
 + 
 +<​code>​http://​nems.local/​nems-api/​{tablename}</​code>​For example, to get all host records from the server, GET 
 + 
 +<​code>​http://​nems.local/​nems-api/​hosts</​code>​ 
 + 
 +==== Columns ==== 
 + 
 +To limit the returned data to a subset of the available fields, pass a Columns query parameter containing a comma-separated list of column names. To fetch the name and services list for all hosts: 
 + 
 +<​code>​http://​nems.local/​nems-api/​hosts?​Columns=name,​services</​code>​ 
 + 
 +==== Filters ==== 
 + 
 +To filter the result set to records meeting some criteria, pass one or more Filter[] params. Each Filter is a urlencoded LQL filter ​(see the [mk-livestatus documentation]([[http://​mathias-kettner.com/​checkmk_livestatus.html#​H1:​LQL|http:​%%//​%%mathias-kettner.com/​checkmk_livestatus.html#​H1:​LQL]] - The Livestatus Query Language) for detailed LQL filter syntax). If more than one filter is specified, they are ANDed together. To get all hosts starting with "​api"​ in state OK (0): 
 + 
 +<​code>​http://​nems.local/​nems-api/​hosts?​Filter[]=name ~ ^api&​Filter[]=state = 0</​code>​ 
 + 
 +==== Stats ==== 
 + 
 +Stats queries allow you to get a count of objects matching a criteria. Stats queries return a list of counts and never take a Columns parameter. You can request several Stats with a single API call. You can also restrict the objects counted by adding Filters to your query. To count the number of hosts starting with "​api"​ in state OK: 
 + 
 +<​code>​http://​nems.local/​nems-api/​hosts?&​Stats[]=name ~ ^api&​Filter[]=state = 0</​code>​ 
 + 
 +===== Command Interface ===== 
 + 
 +All calls to ''​%%nems-api%%''​ to execute Nagios commands **must be HTTP POST requests**. 
 + 
 +==== Acknowledgements ==== 
 + 
 +Acknowledgements for host and service alerts can be sent via the ''​%%acknowledge_problem%%''​ endpoint. 
 + 
 +=== Acknowledge Host Alerts === 
 + 
 +<​code>​curl -is -XPOST https://​nems.local/​nems-api/​acknowledge_problem -d '​{"​host":​ "​host.example.com",​ "​author":​ "​rfrantz",​ "​comment":​ "acked from livestatus"​}'</​code>​ 
 + 
 +=== Acknowledge Service Alerts === 
 + 
 +Acknowledging service alerts is similar to host alerts, with the addition of the ''​%%service%%''​ parameter:​ 
 + 
 +<​code>​curl -is -XPOST https://​nems.local/​nems-api/​acknowledge_problem -d '​{"​host":​ "​host.example.com",​ "​service":​ "​Apache",​ "​author":​ "​rfrantz",​ "​comment":​ "acked from livestatus"​}'</​code>​ 
 + 
 +==== Downtime ==== 
 + 
 +=== cancel_downtime === 
 + 
 +Existing scheduled downtimes for a host can be canceled. ''​%%cancel_downtime%%''​ expects the ''​%%downtime_id%%''​ parameter. Downtime IDs can be found by querying a host and extracting the ''​%%downtimes%%''​ array: 
 + 
 +<​code>​curl -s https://​nems.local/​nems-api/​hosts?​Filter=name = my_host | jq '​.'​ | grep '​downtimes"'​ -A 2 
 + 
 +"​downtimes":​ [ 
 +    12345 
 +], 
 +</​code>​ 
 + 
 +The subsequent request to cancel the host's downtime is: 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​cancel_downtime'​ -d '​{"​downtime_id":​ "​12345"​}'</​code>​ 
 + 
 +To cancel the downtime for a service, pass the name of the service along with the downtime_id:​ 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​cancel_downtime'​ -d '​{"​downtime_id":​ "​12345",​ "​service":​ "​CPU"​}'</​code>​ 
 + 
 +=== schedule_downtime === 
 + 
 +Schedule downtime for a host as follows: 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​schedule_downtime'​ -d '​{"​host":​ "​host.example.com",​ "​duration":​ "​7200",​ "​author":​ "​rfrantz",​ "​comment":​ "​Downtimed via livestatus"​}'</​code>​ 
 + 
 +**NOTE**: The ''​%%duration%%''​ field expects a value whose unit is in seconds. 
 + 
 +Downtimes can be scheduled for a particular service by adding a ''​%%"​service"​%%''​ parameter:​ 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​schedule_downtime'​ -d '​{"​host":​ "​host.example.com",​ "​service":​ "​CPU",​ duration":​ "​7200",​ "​author":​ "​rfrantz",​ "​comment":​ "​Downtimed via livestatus"​}'</​code>​ 
 + 
 +==== Notifications ==== 
 + 
 +=== disable_notifications === 
 + 
 +Notifications for a host, a host's service, or all of the host's services can be disabled via the ''​%%disable_notifications%%''​ endpoint. 
 + 
 +== Disable Host Notifications == 
 + 
 +Send a request that includes a valid '​host'​ value: 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​disable_notifications'​ -d '​{"​host":​ "​host.example.com"​}'</​code>​ 
 + 
 +== Disable Notifications for a Host's Service == 
 + 
 +Send a request that includes valid '​host'​ and '​service'​ values: 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​disable_notifications'​ -d '​{"​host":​ "​host.example.com",​ "​service":​ "​httpd"​}'</​code>​ 
 + 
 +== Disable Notifications for All of a Host's Services == 
 + 
 +Send a request that includes a valid '​host'​ value and set '​scope'​ to '​all':​ 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​disable_notifications'​ -d '​{"​host":​ "​host.example.com",​ "​scope":​ "​all"​}'</​code>​ 
 + 
 +=== enable_notifications === 
 + 
 +Notifications for a host, a host's service, or all of the host's services can be enabled via the ''​%%enable_notifications%%''​ endpoint. 
 + 
 +== Enable Host Notifications == 
 + 
 +Send a request that includes a valid '​host'​ value: 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​enable_notifications'​ -d '​{"​host":​ "​host.example.com"​}'</​code>​ 
 + 
 +== Enable Notifications for a Host's Service == 
 + 
 +Send a request that includes valid '​host'​ and '​service'​ values: 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​enable_notifications'​ -d '​{"​host":​ "​host.example.com",​ "​service":​ "​httpd"​}'</​code>​ 
 + 
 +== Enable Notifications for All of a Host's Services == 
 + 
 +Send a request that includes a valid '​host'​ value and set '​scope'​ to '​all':​ 
 + 
 +<​code>​curl -s -XPOST '​https://​nems.local/​nems-api/​enable_notifications'​ -d '​{"​host":​ "​host.example.com",​ "​scope":​ "​all"​}'</​code>​
  • features/nems-api.1534970866.txt.gz
  • Last modified: 2019/02/04 11:34
  • (external edit)