Creating a host through the Icinga 2 API

by | Jul 2, 2020

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 setup
…which should result in a:

information/cli: Enabling the 'api' feature.
Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.

 

This will automatically set up an API root user with a generated password under /etc/icinga2/conf.d/api-users.conf:
object ApiUser "root" {
  password = "c63c009b83429426"
  // client_cn = ""
  permissions = [ "*" ]
}
Looking good! Obviously you can use the generated password, but editing the file with your own password will make your life easier, trust me.
object ApiUser "root" {
  password = "icinga"
  // client_cn = ""
  permissions = [ "*" ]
}

 

Let’s do a quick check if the authentication works:
curl -k -s -S -u root:icinga 'https://localhost:5665/v1

 

If you get this output:
<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>
…you’re good to go!

 

So, now, how about that host object?
This instruction is the very least requirement for adding a host object named “myhostobject” to your Icinga.
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!

You May Also Like…

Subscribe to our Newsletter

A monthly digest of the latest Icinga news, releases, articles and community topics.