Learning about the Icinga API can be an eye opening moment for some, and lead to a path of automation and configuration management. But where to start? Well, you can always check out the Icinga API documentation for that. But today, I have an idea for you – I’ll show you how to create a host through the Icinga 2 API.
But first, let’s set up the Icinga 2 API, which is as easy as using…
icinga2 api setupinformation/cli: Enabling the 'api' feature.
Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
object ApiUser "root" {
password = "c63c009b83429426"
// client_cn = ""
permissions = [ "*" ]
}
object ApiUser "root" {
password = "icinga"
// client_cn = ""
permissions = [ "*" ]
}
curl -k -s -S -u root:icinga 'https://localhost:5665/v1
<html><head><title>Icinga 2</title></head><h1>Hello from Icinga 2 (Version: v2.11.0-473-g18eb06e33)!</h1><p>You are authenticated as <b>root</b>. Your user has the following permissions:</p> <ul><li>*</li></ul><p>More information about API requests is available in the <a href="https://icinga.com/docs/icinga2/latest/" target="_blank">documentation</a>.</p></html>
curl -k -u root:icinga -H 'Accept: application/json' \
-X PUT 'https://localhost:5665/v1/objects/hosts/myhostobject' \
-d '{ "attrs": { "address": "192.168.1.1", "check_command": "hostalive"}}'
Let’s see what’s happening here:
-k: We’re using this for skipping the verfication of the SSL connection to your webserver
-u: This attribute will provide your curl query with the Icinga 2 API user name and password in the format user:password, in this case root:icinga
-H: This will tell curl to expect json output, which the Icinga 2 API provides
-X: A http request, in this case, PUT, which adds information. Other options include GET for getting information, maybe concering hosts or services
–d: Data which will be added to your request – imagine filling out a form online with this information, which is the most interesting part of the request. This is where you will enter all the relevant information concerning hosts, like the OS they run on, or other attributes which you’d normally enter in your configuration files. But with the Icinga API, stuff like this is possible:
curl -k -s -S -u root:icinga -H 'Accept: application/json' \
-X PUT 'https://localhost:5665/v1/objects/hosts/myhostobject' \
-d '{ "templates": [ "generic-host" ], "attrs": \
{ "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }'
Good luck and have fun toying around with the Icinga API and adding your first hosts from the CLI!
