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.nagiosexchange.org, and since op5 Monitor and Nagios uses the same plugin format you can often simply download a plugin, put it in /opt/plugins/custom/ and start using it.

However, if you can not find a suitable plugin anywhere you might have to write your own plugin. Since the plugin interface is very straight-forward, anyone with a fair amount of UNIX scripting experience can do this. 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.

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.

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. On the op5 server there are two popular editors that you could use for this purpose: vim and jed.

vim is a very capable mode based editor that has a high usability threshold, whilst jed is also a capable text editor that is friendlier to first time users. If you do not know what you want to use, it is a good idea to start with jed. If you want to use jed, you need to have a terminal with light text and dark background to see the text.

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 on stdout (will be shown in the web gui)
• Returns an exit code of 0, 1 or 2 for OK, Warning or Critical

Example

monitor!root:~# /opt/plugins/check_tcp -H 193.201.96.136 -p 80
TCP OK – 0.043 second response time on port 80|time=0.042824s;0.000000;0.000000;0.000000;10.000000
monitor!root:~# echo $?
0
monitor!root:~# /opt/plugins/check_tcp -H 193.201.96.136 -p 143
Connection refused
monitor!root:~# echo $?
2
monitor!root:~#

in this example we first execute check_tcp to test that port 80/tcp on 193.201.96.136 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

Create a script and start a text editor like this:

cd /opt/plugins/custom
touch helloworld
chmod 755 helloworld
jed helloword

When you have jed running you’ll find that the menus can be accessed with arrow keys and enter after pressing F10 to activate them.

Type in the following example plugin:

#!/bin/sh
echo ‘WARNING: Hello world!’
exit 1

Then choose Exit from the File menu or press ^C^X and then type yes to save it.

Now try running it from the terminal:

monitor!root:/opt/plugins/custom# ./helloworld
WARNING: Hello world!
monitor!root:/opt/plugins/custom# echo $?
1
monitor!root:/opt/plugins/custom#

Configuring monitor to use the plugin

Go to Configure in the web gui, and choose Check Commands

Scroll to the bottom of the page to add a new command. Call it something that makes it stand out from the other commands – to make it easier in the future. For instance:

command_name: check_local_helloworld
command_line: $USER1$/custom/helloworld

then select Apply 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 op5backup.sh is configured properly for local operation – this test will not necessarily succeed if you put your op5backup files on an FTP account.

Start by creating the script and editing it:

cd /opt/plugins/custom
touch check_op5backup
chmod 755 check_op5backup
jed check_op5backup

#!/usr/bin/env/bash
# Create a function to print the storagepath
storagepath() {
grep ^storagepath /etc/op5backup.conf |
tail -1 |
sed ‘s/^[^"]*”//g’ | sed ‘s/”$//g’
}
# Put the storage path in an environmental variable
STORAGEPATH=`storagepath`
# Test if the storagepath exists and is a directory
if [[ ! -d "$STORAGEPATH" ]]; then
# Print a warning message for the web gui
echo op5backup.sh is not properly configured for local operation
# Exit with status Warning (exit code 1)
exit 1
fi
# If the script reaches this point then the test passed
# Print an OK message
echo $STORAGEPATH exists
# Exit with status OK
exit 0

Now add a check_command like this using the op5 Monitor web gui:

command_name: check_op5backup
command_line: $USER1/custom/check_op5backup

Enter the service configuration for your monitor server, and add a service with check_op5backup as the check_command.

Save configuration and try it out!

Other examples

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 Nagiosplugins-website (latest sources are listed at sourceforge).

• Perl example
• C example