Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
features:nems-api [2018/08/22 18:07]
Robbie Ferguson
features:nems-api [2019/02/04 11:35] (current)
Line 16: Line 16:
 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. 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.
  
-====Commands====+====Secure Certificate====
  
-  * **https://nems.local/nems-api/hosts** - output all configured hosts +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.
-  * **https://nems.local/​nems-api/​services** - output all configured services +
-  * **https://nems.local/​nems-api/​downtimes** - output all scheduled downtimes+
  
-====Secure Certificate====+====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':​
  
-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).+<​code>​curl ​-s -XPOST '​https:​//nems.local/nems-api/enable_notifications' ​-d '​{"​host":​ "host.example.com",​ "​scope":​ "​all"​}'</​code>​
  • features/nems-api.1534975658.txt.gz
  • Last modified: 2019/02/04 11:34
  • (external edit)