op5 Monitor is shipped with many plugins that cover most monitoring needs. But what to do if one of your corporate applications can not be monitored straight out of the box? Often you can find a plugin at www.monitoring-plugins.org or www.nagiosexchange.org, and since op5 Monitor, Naemon and Nagios uses the same plugin format you can often simply download a plugin, put it in the correct directory and start using it.
However, if you can not find a suitable plugin anywhere you might have to write your own plugin. This article aims to describe the format and walk you through writing a simple plugin. It is intended for the op5 system administrator who wants to extend the capabilities of an op5 System and leave the boss impressed with how precise data can be extracted.
- Scripting/Programming knowledge
- Root-privileges on the host system running op5 Monitor
Accessing and editing files
In order to develop plugins of your own, you will need shell access and sometimes the possibility to transfers files to and from the op5 server.
If you do not already have this, software that can provide this for Windows is PuTTY for terminal access via SSH and WinSCP for file transfers via SFTP (SSH). If you use a Macintosh or UNIX/Linux desktop you can use the commands ssh or scp from a local terminal window.
You will need to use a text editor to write your plugin. The OP5 server comes with the editor "vi".
Paths and check_commands
Most of the plugins are installed by default in /opt/plugins/ which is also what $USER1$ expands to when you define check_commands. There is a subdirectory called /opt/plugins/custom/ that is intended for site specific plugins, such as downloaded plugins or plugins that has been written specifically for the site. This directory is hence $USER1$/custom/ when you define check_commands.
The plugin interface
A plugin is a small executable that takes optional command line parameters as input and
- Performs a test
- Reports a diagnostic message to stdout (will be shown in the web gui)
- Returns an exit code of 0, 1, 2 or 3 for OK, Warning, Critical or Unknown
In this example we first execute check_tcp to test that port 80/tcp on 126.96.36.199 responds which it does, hence the exit code of 0. Then we check port 143/tcp on the same host and that port is not open, hence the result is Critical ? exit code 2.
Also note that the output is actually divided by a | sign. The text on the left hand side of | will be shown in the web interface, whilst the text on the right hand side will only be stored as performance data ? amongst others for the graph button you can find to the right of some services name.
Creating a Hello world plugin
Change directory to /opt/plugins/custom, create a file called "helloworld", set execution permissions on this file and open it with a text editor. This example uses the editor "vi".
Type in the following example plugin:
Now try running it from the terminal:
Configuring monitor to use the plugin
Go to Manage ? Configure in the web gui, and choose Commands
Name it something that makes it stand out from the other commands ? to make it easier in the future. For instance:
Then click Submit changes and save configuration.
Now you can add this command as a service for your hosts.
Writing a useful plugin
By now you probably have a very basic hello world plugin running. This is hardly useful though, so we shall look at creating a more complex and useful one. We'll stick to bash, because of the simplicity, but in theory we could use any programming language.
We will create a plugin that checks that the storage path specified in /etc/op5backup.conf exists, to make sure that op5-backup is configured properly for local operation ? this test will not necessarily succeed if you put your op5-backup files on an FTP account.
Start by creating the script and editing it:
Now add a check_command like this using the op5 Monitor web gui:
Enter the service configuration for your monitor server, and add a service with check_op5-backup as the check_command.
Save configuration and try it out!
Since many people find examples an easy way of learning, the following links provides an example of a really simple plugin written in both Perl and C. The plugin takes one argument, a filename, and returns OK if the file exists and CRITICAL if it does not. They also include timeout-handling.
In order to use the perl example you only need the copy the file into the /opt/plugins directory of the monitor-server. In order to compile the C-version, you need to rebuild the plugins-package from source. The source can be found at the Monitoring-plugins website.