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:
HTTP, POP3, IMAP, FTP, SSH, DHCP
CPU Load, Disk Usage, Memory Usage, Current Users
Unix/Linux, Windows, and Netware Servers
Routers and Switches
etc.
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:
Nagios Plugins Project: http://nagiosplug.sourceforge.net/
Nagios Downloads Page: http://www.nagios.org/download/
IcingaExchange.org: http://www.monitoringexchange.org
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 |
---|---|
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
command_name: this is a short name identifying the command, let's use check_sample
command_line: here you define the command to execute. You can specify the command you executed on the command line but that would be very inflexible. Normally the plugin directory (/usr/local/icinga/libexec) remains the same so we can use a $USERn$ variable which is defined in resource.cfg. The IP-address changes from host to host. There is a macro called $HOSTADDRESS$ which we can use for that purpose. The value of the arguments may vary so these should be flexible, too. This may lead to the following definition:
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.
"...resulted in a return code of 127"
This means the plugin was not found at the specified location or that a file called from within the plugin was not found. If you use $USERn$ macros calling the plugin then make sure that the macro really points to the location where the plugin is (is the macro defined in resource.cfg?). Notification commands often call a mail program. Make sure that the path to the mail program is correct.
"...resulted in a return code of 13"
Mostly this indicates a permissions problem. The user might not be able to access / execute the plugin and/or other related files. This might happen if you tested a plugin as root which creates temporary files. The Icinga user is not allowed to overwrite these files.
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.
© 2009-2010 Icinga Development Team, http://www.icinga.org