How to connect to the Icinga 2 API via the Icinga Console

by | Feb 11, 2021

Today I will show you a couple of small functions you can use with the Icinga Console. Using the Icinga Console can help with scripting in general and provides a quick and easy-to-use way of extracting information from your Icinga environment.

We will take a look at extracting information belonging to the service objects in Icinga. Obviously, you can pinpoint different objects, like host objects, with which you can work via the Icinga 2 API and Console. To keep it simple, I’ll just show you a couple of example commands today. Feel free to play around with them in your Icinga console!

First of all, we need to connect with the Icinga API by using the following command:

$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: r2.12.3-1)
Type $help to view available commands.
<1> =>

Now our Icinga Console is connected to the API and we can run commands that display information directly from Icinga.


Next, we take a look at our services. Let’s find out the names of all the services we have running by using the following command:

=> func = []; for (s in get_objects(Service)) {func.add(s.__name)}; func
[ "blgtst!ping6", "blgtst!http", "blgtst!ssh", "blgtst!disk /", "blgtst!icinga", "blgtst!procs", "blgtst!ping4", "blgtst!users", "blgtst!swap", "blgtst!disk", "blgtst!load", "blgtst!apt" ]

This creates a function func, which is being filled by an iterating for loop extracting the name of the services. By calling func, we print the contents of the array to the console.


In the next step we add some information relating to the services we would like to extract from Icinga. The following command adds the current service state to each of the names of the services:

=> func1 = []; for (s in get_objects(Service)) {func1.add([s.__name, s.state])}; func1
[ [ "blgtst!ping6", 0.000000 ], [ "blgtst!http", 0.000000 ], [ "blgtst!ssh", 0.000000 ], [ "blgtst!disk /", 0.000000 ], [ "blgtst!icinga", 0.000000 ], [ "blgtst!procs", 0.000000 ], [ "blgtst!ping4", 0.000000 ], [ "blgtst!users", 0.000000 ], [ "blgtst!swap", 2.000000 ], [ "blgtst!disk", 0.000000 ], [ "blgtst!load", 0.000000 ], [ "blgtst!apt", 2.000000 ] ]



Still down for more tricks? Now that we’ve gotten every service and it’s current state printed to the console, let’s try expanding our command to also print the date and time of the last critical state of each service. We use the DateTime.to_string() function for that. Our command now looks as follows:

=> func2 = []; for (s in get_objects(Service)) {func2.add([s.__name, s.state, DateTime(s.last_state_critical).to_string()])}; func2
[ [ "blgtst!ping6", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!http", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!ssh", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!disk /", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!icinga", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!procs", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!ping4", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!users", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!swap", 2.000000, "2021-02-10 16:35:15 +0000" ], [ "blgtst!disk", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!load", 0.000000, "1970-01-01 00:00:00 +0000" ], [ "blgtst!apt", 2.000000, "2021-02-10 16:35:16 +0000" ] ]

Now that’s some information! But how would you create your own commands based on what we’ve looked at today? Well, I’ve got three places where you can look and search for what type of information you’d want to extract from your Icinga environment.


Check out the Icinga Library Reference for all things concering the Icinga Console and it’s usable functions – you’ll find a lot of different ways in which you can extract, filter and manipulate information there.

Take a look at the Runtime Macros – macros with which you can an objects attributes.

And, a little trick that gets overlooked a lot – the Icinga Console offers an auto completion feature! With that, all of the available options of objects can be displayed in a neat way. Have fun experimenting and finding the right combination for your environment – regardless if you’re debugging, experimenting or administering your Icinga.

You May Also Like…

Icinga Camp Berlin 2023

It’s time to spread some monitoring love! We’re super happy to announce our next Icinga Camp in Berlin, on May 17th, 2023

How Tenacta Group uses Icinga

How Tenacta Group uses Icinga

This is a blogpost from Livio Daina from Tenacta Group Tenacta Group is an Italian company with a portfolio of...

Subscribe to our Newsletter

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