There are multiple ways to interact programatically with Icinga. Last week Henrik demonstrated how to connect to the Icinga 2 API through the Icinga 2 Console. Working with the Icinga 2 API is probably the most obvious way to interact with Icinga. Still, I would like to suggest to you another option: How you can fetch data from Icinga Web.
Exporting Data
Let’s get started with the most simple use case: Export data directly through Icinga Web. Let’s say you are looking at the Tactical Overview that shows you a bunch of numbers about the amount of hosts and services and their states. Wouldn’t it be nice if you could get those numbers in a format that can be processed by other tools?
You can do exactly that by adding just another parameter to the URL: format=json Actually the format parameter supports two different options, JSON and CSV.
Your URL would look something like this: http://localhost/icingaweb2/monitoring/tactical?format=json
You said Programatically
Now that you know how to export the data in general, let’s see how you can use curl to do it on the command line. First of all you need access to Icinga Web. If you’re collecting the data with a script, it’s recommended to have a separate API user with the right amount of permissions.
First create a separate role that has only “General Module Access” to the “monitoring” module, that’s enough for you to collect the data. Give the role a recognisable name like “API Role” or similar. Afterwards create a new user and assign it to the API role.
The only thing that’s important for your API request is setting the right headers. That’s how Icinga Web distinguishes between API requests and actual browsers and will not try to set cookies.
The example: Tactical Overview as JSON output collected with cURL:
curl -k -u 'api-user:api-password' -H 'Accept: application/json' 'http://localhost/icingaweb2/monitoring/tactical'
I skipped the additional parameter in the URL, because Icinga Web will deliver a valid JSON output automatically.
Where to Use
The Tactical Overview is a good example for demonstrating how you can get the data out of Icinga Web. There are many use cases where this functionality comes in handy. You can get the data as JSON format from almost every view within Icinga Web. Basically everywhere where you see the filter editor. Depending on the view you will get different details. Some examples are:
- Detail View of a Host/Service: Shows you all the details of that Host/Service, including the current state, groups, contacts etc.
- Host/Service Overview: Gets all the details for a list of Hosts/Services, including their state, output and more.
- Host-/Servicegroup Overview: Returns statistics about all Host- and Servicegroups
- History: Returns a list of all state changes, acknowledgements, downtimes, notifications and more. Take care that your web server can handle your request and filter out unnecessary results.
Talking about the filter editor: Of course you can create your custom filtered view and use it for data export as well.
