Icinga

Icinga Plugins

Introduction

Unlike many other monitoring tools, Icinga does not include any internal mechanisms for checking the status of hosts and services on your network. Instead, Icinga relies on external programs (called plugins) to do all the dirty work.

What Are Plugins?

Plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.) that can be run from a command line to check the status or a host or service. Icinga uses the results from plugins to determine the current status of hosts and services on your network.

Icinga will execute a plugin whenever there is a need to check the status of a service or host. The plugin does something (notice the very general term) to perform the check and then simply returns the results to Icinga. Icinga will process the results that it receives from the plugin and take any necessary actions (running event handlers, sending out notifications, etc).

Plugins As An Abstraction Layer

Plugins act as an abstraction layer between the monitoring logic present in the Icinga daemon and the actual services and hosts that are being monitored.

The upside of this type of plugin architecture is that you can monitor just about anything you can think of. If you can automate the process of checking something, you can monitor it with Icinga. There are already a lot of plugins that have been created in order to monitor basic resources such as processor load, disk usage, ping rates, etc. If you want to monitor something else, take a look at the documentation on writing plugins and roll your own. Its simple!

The downside to this type of plugin architecture is the fact that Icinga has absolutely no idea what it is that you're monitoring. You could be monitoring network traffic statistics, data error rates, room temperate, CPU voltage, fan speed, processor load, disk space, or the ability of your super-fantastic toaster to properly brown your bread in the morning... Icinga doesn't understand the specifics of what's being monitored - it just tracks changes in the state of those resources. Only the plugins themselves know exactly what they're monitoring and how to perform the actual checks.

What Plugins Are Available?

There are plugins currently available to monitor many different kinds of devices and services, including:

Obtaining Plugins

Plugins are not distributed with Icinga, but you can download the official Nagios plugins and many additional plugins created and maintained by Nagios and Icinga users from the following locations:

How Do I Use Plugin X?

Most all plugins will display basic usage information when you execute them using '-h' or '--help' on the command line. For example, if you want to know how the check_http plugin works or what options it accepts, you should try executing the following command:

 ./check_http --help
[Important] Important

Always execute the plugin using the Icinga user because some plugins will create temporary files. If you're testing plugins with another user then the Icinga user may not have the permissions to overwrite existing files.

Don't call the plugin using relative paths (i.e ./check_test_plugin). Always use absolute paths because that's the way Icinga does it (i.e. /usr/local/icinga/libexec/check_test_plugin).

Integrating a new plugin

If you want to integrate a new plugin then please read the documentation (if any) before installing it. It may contain important information about the prerequisites like additional packages, (perl) modules and on how to install the plugin together with hints for your distribution.

Sometimes you have to compile the plugin preparing the compile process using "./configure" with or without options. Please check the file config.log for errors regarding missing (devel) packages before issuing the actual compile command (mostly "make" or "make all"). In most cases the plugin is copied to the plugins directory (i.e. /usr/local/icinga/libexec) during "make install".

Sometimes you have to alter the plugin to reflect your environment (i.e. path to "utils.pm", ...). Normally you have to copy it manually to the plugins directory (i.e. /usr/local/icinga/libexec).

After the installation of the plugin call it from the command line using the appropriate options. If this works then you can integrate it into Icinga.

Let's imagine you used the following call on the command line

 /usr/local/icinga/libexec/sample-plugin.pl -H 192.168.1.2 -a argument1 -p parameter -n 5

The command definition has to contain two directives

 define command{ 
    command_name check_sample
    command_line $USER1$/sample-plugin.pl -H $HOSTADDRESS$ -a $ARG1$ -p $ARG2$ -n $ARG3$
    }

Then we have to define the check_command directive which is part of the host/service definition starting with the short name followed by the arguments separated by exclamation marks (!):

 check_command check_sample!argument1!parameter!5

As you can see the IP-address is not specified because it is taken from the host definition.

Check the configuration using "/etc/init.d/icinga show-errors" and resolve any errors before issuing "/etc/init.d/icinga restart". Wait until the object is checked and look at the status details. There might be errors.

Plugin API

You can find information on the technical aspects of plugins, as well as how to go about creating your own custom plugins here.