Icinga 2

Thola can be used as a check command for Icinga 2.

The check subcommand of the thola binary and the thola-client binary returns its check results in an icinga compatible format per default.

When integrating Thola into Icinga 2, we recommend using the thola-client binary together with a Thola API for better performance. Thola’s caching system for example works better in API mode and the configuration only needs to be loaded once when starting the API, and not for every single executed check.

Therefore we will explain the integration into Icinga 2 by using the client binary. If you do not want to use an API, you can simply exchange thola-client with thola in the given example configurations and remove the --target-api command line flag.

If you are using a distributed Icinga 2 network with multiple satellites, we recommend having a Thola API running on every satellite that uses Thola to communicate with your devices. The thola-client binary can be configured as a check command and send request to the API using localhost. In the following we are going to assume you have a Thola API running on http://localhost:8237 on each Icinga server.

Note: If you don’t use an API and have multiple checks running concurrently, do not use Thola’s default build-in caching database, as it’s only capable to communicate with one process at a time.

Check command templates

Thola can be directly used as a check command for Icinga 2. We use a check command template which contains the main information that is required for every request. Since there are some subcommands that do not receive any information about a network device, we create a separate template for the device information, like the ip address, snmp connection data etc.

Our base check command template configuration looks like this:

template CheckCommand "generic-thola" {
    import "plugin-check-command"
    command = [ "/check-commands/thola-client" ]
    arguments += {
        "(no key.0)" = {
            description = "Thola Mode"
            order = -2
            required = true
            skip_key = true
            value = "check"
    }
    "--target-api" = {
        description = "address of the thola api"
        required = true
        value = "http://localhost:8237"
        }
    }
    ...
}

It defines that we always use the check subcommand by setting an argument with no key to positon -2. The value of this argument is the Thola mode that will be used. It also defines the address of the Thola API we are using. Other global options that are available for every subcommand, like which caching method we would like to use, can be defined here too.

If we do not use a Thola API and instead of thola-client use the thola binary, we can simply replace the command path and remove the --target-api flag.

Now we create the second check command template for checks that require device connection information:

template CheckCommand "generic-thola-device" {
    import "generic-thola"

    arguments += {
        "--ip" = {
            required = true
            value = "$address$"
        }
        "--snmp-community" = {
            required = false
            value = "$snmp_community$"
        }
        "--snmp-version" = {
            required = false
            value = "$snmp_version$"
        }
        ...
    }
}

These device specific information should usually be stored as host variables for each network device, so they can be accessed from multiple checks.

Check commands

Now we can create a new check command for every subcommand of thola check. For normal checks that monitor a network device we import the generic-thola-device subcommand. Other checks that do not require device specific information, like check thola-server, which is used for monitoring a Thola API, we use the generic-thola template.

The configuration of a check command that executes check thola-server looks like this:

object CheckCommand "thola-server" {
    import "generic-thola"

    arguments += {
        "(no key)" = {
            order = -1
            required = true
            skip_key = true
            value = "thola-server"
        }
    }
}

It only defines that we use the subcommand check thola-server. This is done by setting an argument with no key to position -1. The value of this argument is the subcommand of the check that will be executed. There are no other flags available for this check, so we do not have any other arguments.

If we want to create a check command for check interface-metrics, which is used to periodically read out interface metrics and return them as performance data, we can create the following configuration:

object CheckCommand "thola-interface-metrics-test" {
    import "generic-thola-device-check-command"

    arguments += {
        "(no key)" = {
            order = -1
            skip_key = true
            value = "interface-metrics"
        }
    }
}

In this case we set interface-metrics as the argument value on position -1.

Here is one last example for check ups, which is used to monitor UPS devices and allows to define some optional thresholds:

object CheckCommand "thola-ups" {
    import "generic-thola-device-check-command"

    arguments += {
        "(no key)" = {
            order = -1
            skip_key = true
            value = "ups"
        }
        "--batt-current-critical-max" = {
            required = false
            value = "$ups_batt_current_critical_max$"
        }
        "--batt-current-critical-min" = {
            required = false
            value = "$ups_batt_current_critical_min$"
        }
        "--batt-current-warning-max" = {
            required = false
            value = "$ups_batt_current_warning_max$"
        }
        "--batt-current-warning-min" = {
            required = false
            value = "$ups_batt_current_warning_min$"
        }
        "--batt-temperature-critical-max" = {
            required = false
            value = "$ups_batt_temperature_critical_max$"
        }
        "--batt-temperature-critical-min" = {
            required = false
            value = "$ups_batt_temperature_critical_min$"
        }
        ...
    }
}

All command line flags that are available for each check can be displayed using the -h or --help option.

Service Templates

Once we defined a check command we would like to use, we can create a service template that uses this command. To do this, we simply create a new service template and set the check_command field.

This configuration shows an example service template for check interface-metrics

template Service "interface-metrics" {
    import "generic-service"

    check_command = "interface-metrics"
}

After that you can create a service object based on this template for all hosts you would like to monitor with this check.