Nagios API

The Nagios API was created to integrate Nagios more closely with CSCF Inventory. It is documented here so it may be useful for other projects as well. Note that at present, the fetch command requires inventory access to update inventory records via Nagios API.

Using the API

To use the API you need to know:

1. The URL
2. The commands avaliable
3. The parameters each POST request requires

In general commands return 200 OK. When an error occurs, an appropriate HTTP error code is returned along with a message describing the cause of the error.

If no API Key is provided HTTP 401 Authorization Required will be returned.

If an incorrect API key is provided HTTP 403 Forbidden will be returned.

Version 1 Commands

There currently are 6 different commands, 5 of which use the same URL structure keyed by IP address, and the 6th using a slightly different one keyed by inventory pKey.

/api/v1/ip/<ipaddress>/<command>

add

Adding a service can be done using this endpoint. Add will also handle creating the host group for a record if this is the first service being added for an ip address. pkey is a mandatory field stored in the database for later inventory record lookup.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
pkey	"12345"	A valid inventory pkey (primary key)
active	"1"	A "1" denotes an active service which should be monitored, and "0" is an inactive service
service	"Service Name"	The name of the service being added. This must be a valid Nagios service as can be found on the Nagios Service List

Ex: /api/v1/ip/192.168.2.1/add

Response:

* 200 OK if success * 500 Internal Server Error if unable to add the service

delete

This command is used to delete a service from a nagios host identified by IP address. The host group will be marked as inactive if the last remaining service within a host group is deleted.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
service	"Service Name"	The name of the service being deleted. This must be a valid Nagios service as can be found on the Nagios Service List

Ex: /api/v1/ip/192.168.2.1/delete

Response:

* 200 OK if success * 500 Internal Server Error if unable to make changes in the database

update_host

This command is used to update the IP address of a host being monitored. Despite the name, this is only used to update the IP address. Updating a hostname (for both nagios and inventory) is done via calling fetch.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
new_ip	"192.168.2.1" or null	The new ip address that the host is being changed to have. The URL should already contain the old ip address which Nagios uses to lookup the item. This can also be null or the same as the old ip address if there is no change.

Ex: /api/v1/ip/192.168.2.1/update_host

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

update_service

This is used to update the active status of a service. You can use it to set a service to active (1) or inactive (0).

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
active	"1"	A "1" denotes an active service which should be monitored, and "0" is an inactive service
service	"Service Name"	The name of the service being updated. This must be a valid Nagios service as can be found on the Nagios Service List

Ex: /api/v1/ip/192.168.2.1/update_service

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

get

Given an ip address or list of ip's (separated with '-'s) Nagios will return a JSON formatted output of avaliable services, registered services, and even any warnings/errors the machine is reporting to Nagios. Using the hyphen/dash character (-) you can lookup multiple ip's at once. This works essentially like a CSV would, except it uses dashes instead of commas. Don't confuse the dashes with being a range of ip's. Nagios API does not support ip ranges.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios

Ex: /api/v1/ip/192.168.2.1/get

Ex: /api/v1/ip/192.168.2.1-127.0.0.1/get (example of getting two ip's results)

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

The get command however also returns a JSON response like the following:

{ 
   "available_services":[ 
      { 
         "name":"name", 
         "desc":"description" 
      } 
   ], 
   "registered_services":[ 
      { 
         "hostname":"hostname.domain.tld",
         "ip":"192.168.2.1",
         "serviceName":"string", 
         "active":"0|1", 
         "status":"OK|WARN|CRITICAL|MISSING SERIVCE|UNKNOWN", 
         "url":"https://nagios..." 
      } 
   ], 
   "messages":[ 
      { 
         "type":"host|service", 
         "status":"OK|WARN|CRITICAL|MISSING SERIVCE|UNKNOWN", 
         "hostName":"hostname.domain.tld", 
         "serviceName":"string", 
         "message":"from nagios", 
         "acknowledged":"0|1", 
         "since":"timestamp", 
         "url":"https://nagios..." 
      } 
   ] 
} 

If there are no registered_services for the ip, the registered_services array will simply be empty. The same goes for the messages array.

/api/v1/pkey/<pkey>/fetch

fetch

Fetch is used to instruct Nagios to grab new data from inventory and update its record. Inventory by default calls this so fetch does not normally need to be called by a program unless inventory records are modified directly via the database.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios

Ex: /api/v1/pkey/12345/fetch

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

Version 2 Commands

There currently are 7 different commands, 6 of which use the same URL structure keyed by IP address, and the 6th using a slightly different one keyed by inventory pKey.

/api/v2/ip/<ipaddress>/<command>

add

Adding a service can be done using this endpoint. Add will also handle creating the host group for a record if this is the first service being added for an ip address. pkey is a mandatory field stored in the database for later inventory record lookup.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
pkey	"12345"	A valid inventory pkey (primary key)
service	"Service Name" or null	The name of the service being added. This must either be a valid Nagios service as can be found on the Nagios Service List or blank if just the host is being added.
priority	"Priority name" or null	The priority to the host to or null if not altering the priority of the host.

Ex: /api/v2/ip/192.168.2.1/add

Response:

* 200 OK if success * 500 Internal Server Error if unable to add the service

delete

This command is used to delete a service from a nagios host identified by IP address. The host group will be marked as inactive if the last remaining service within a host group is deleted.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
service	"Service Name" or "false"	The name of the service being deleted. This must either be a valid Nagios service as can be found on the Nagios Service List or blank to remove the host

Ex: /api/v2/ip/192.168.2.1/delete

Response:

* 200 OK if success * 500 Internal Server Error if unable to make changes in the database

update_host

This command is used to update the IP address of a host being monitored. Despite the name, this is only used to update the IP address. Updating a hostname (for both nagios and inventory) is done via calling fetch.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
new_ip	"192.168.2.1" or null	The new ip address that the host is being changed to have. The URL should already contain the old ip address which Nagios uses to lookup the item. This can also be null or the same as the old ip address if there is no change.
priority	"Priority name" or null	The priority to the host to or null if not altering the priority of the host.

Ex: /api/v2/ip/192.168.2.1/update_host

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

schedule_downtime

This overrides any previously set downtime for the specified items.

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
username	"jhvisser"	The username of the person scheduling the downtime. This field is required by nagios.
reason	"ST#1234567 - I am bring this machine down for maintenance" or null	An optional reason that can be given for a scheduled downtime which will be shown in nagios/inventory.
start	1410824	An epoch time indicating when the scheduled downtime will start
end	1412824	An epoch time indicating when the scheduled downtime will end
service	"Service Name" or null	The name of the service being unscheduled. If this is being applied to a whole host then this can be left null. This must be a valid Nagios service as can be found on the Nagios Service List

Ex: /api/v2/ip/192.168.2.1/schedule_downtime

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

unschedule_downtime

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios
username	"jhvisser"	The username of the person scheduling the downtime. This field is required by nagios.
service	"Service Name" or null	The name of the service being unscheduled. If this is being applied to a whole host then this can be left null. This must be a valid Nagios service as can be found on the Nagios Service List

Ex: /api/v2/ip/192.168.2.1/unschedule_downtime

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

get

Given an ip address or list of ip's (separated with '-'s) Nagios will return a JSON formatted output of avaliable services, registered services, and even any warnings/errors the machine is reporting to Nagios. Using the hyphen/dash character (-) you can lookup multiple ip's at once. This works essentially like a CSV would, except it uses dashes instead of commas. Don't confuse the dashes with being a range of ip's. Nagios API does not support ip ranges.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios

Ex: /api/v2/ip/192.168.2.1/get

Ex: /api/v2/ip/192.168.2.1-127.0.0.1/get (example of getting two ip's results)

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

The get command however also returns a JSON response like the following:

{
   "priorities":{
      "default":"B",
      "available":[
         "A",
         "B",
         "C"
      ]
   },
   "available_services":[
      {
         "name":"name",
         "desc":"description"
      }
   ],
   "hosts":[
      {
         "name":"hostname.domain.tld",
         "ip":"192.168.2.1",
         "status":"OK|DOWN|UNREACHABLE|UNKNOWN",
         "url":"http://nagios...",
         "priority":"A",
         "scheduled_downtime":"YES|NO|PARTIAL",
         "downtime_start":14108,
         "downtime_end":14208,
         "services":[
            {
               "name":"string",
               "active":"NO|YES",
               "status":"OK|WARN|CRITICAL|UNKNOWN",
               "url":"https://nagios...",
               "scheduled_downtime":"YES|NO|PARTIAL",
               "downtime_start":14108,
               "downtime_end":14208,
               "components":[
                  {
                     "name":"component name",
                     "status_info":"OK - 1/1 Perfect Machine",
                     "perf_data":"ISO200202 = 1",
                     "status":"OK|WARN|CRITICAL|DISABLED|UNKNOWN",
                     "scheduled_downtime":"YES|NO",
                     "downtime_start":14108,
                     "downtime_end":14208,
                     "url":"https://nagios..."
                  }
               ]
            }
         ]
      }
   ],
   "messages":[
      {
         "type":"host|service",
         "status":"OK|WARN|CRITICAL|DOWN|UP|UNKNOWN",
         "hostName":"hostname.domain.tld",
         "serviceName":"string",
         "message":"from nagios",
         "acknowledged":"0|1",
         "since":"timestamp",
         "url":"https://nagios..."
      }
   ]
}

If there are no registered_services for the ip, the registered_services array will simply be empty. The same goes for the messages array.

/api/v2/pkey/<pkey>/fetch

fetch

Fetch is used to instruct Nagios to grab new data from inventory and update its record. Inventory by default calls this so fetch does not normally need to be called by a program unless inventory records are modified directly via the database.

POST

Key	Example Data	Explanation
api_key	"xxrrXAEcuUQLYZon1cMiPxeDmyZPEw"	An API key generated from Nagios

Ex: /api/v2/pkey/12345/fetch

Response:

200 HTTP OK if success, or appropriate HTTP error code on fail.

Inventory Dependencies

There are a few parts of the API which depend on specifics in Inventory.

URLs

The inventory JSON endpoint URL is used by the fetch operation to get the data from inventory. The search URL is used by fetch to lookup the PKey, if needed, and by the notification emails to link to inventory. The main edit URL is displayed in the Nagios interface to link directly to the machine in inventory (as the 'action' URL). The definitions for these URLs may be found in the configuration files, specifically `etc/api.conf` and `etc/main.conf`. The definitions for the notification URLs may be found in the `notify-host-by-email` and `notify-service-by-email` commands in NagiosQL, please note that these are complete email commands and will likely need to be copied to a text editor for editing.

JSON Data

Additionally the fetch operation depends on the data returned by the JSON URL, if the format of that changes the API will need to be updated. The relevant code may be found in `bin/Fetch.php` in the function `getInventoryData()`. If the only change is which fields are CSV for multiple DNS entries, then that may be configured by changing the `inventory:api:csvfields` option in `etc/main.conf`. It should be a comma and space separated list of fields which should be expected to be in CSV format with one entry for each DNS entry on the machine.

-- DennisBellinger - 2016-05-25