skip to main content
Plugins
  
Plugins
Introduction
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.
Paths and macros
All standard plugins shipped with op5 Monitor are installed in:
/opt/plugins
The macro you use to reach the plugins folder is:
$USER1$
The plugins you add to the system by your own must be placed in:
/opt/plugins/custom
And they will then be reached with the following macro/path:
$USER1$/custom
The reason for placing your own plugins in /opt/plugins/custom is because then they will not be touched by any upgrade from op5.
Before you start
Befor you can start developing you own plugins you need to make sure you have SSH access or terminal access to your op5 server the possibility to transfer files to your op5 Monitor server any kind of editor, vim and jed are installed by default on your op5 Monitor server.
 
 
Microsoft Windows users may use PuTTY for terminal access via SSH and WinSCP for file transfers via SFTP (SSH).
Macintosh or UNIX/Linux users may use the commands ssh or scp from a local terminal window.
The plugin interface
A plugin is a small executable that takes optional command line parameters as input and
1 Performs a test
2 Reports a diagnostic message on stdout (will be shown in the web GUI)
3 Returns an exit code.
Example 1 Execute check_tcp to test the port 80/tcp on 193.201.96.136
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 the Example 1 on page 91 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.
The result output is actually built upon two parts divided by a | sign (pipe). The text on the
left hand side of the | is the status information
right hand side of the | is the performance data.
 
 
The performance data is not mandatory but you need it if you want your plugin to be able to produce graphs for you in op5 Monitor.
 
Status output
The Status output is the text describing the result in human readable form. The plugin must print the status output to stdout when your plugin is executed.
You will see it in the Status state information on the Service or Host information page.
This text can be anything, you like to use to describe the status situation for your plugin, including HTML.
 
Performance data
The performance data is data displaying the result in numbers. The plugin must print the status output to stdout when your plugin is executed. It is also to produce performance graphs in op5 Monitor.
So if you want graphs from your plugin you need to have performance data in your output.
The performance data is setup like this:
'label'=value[UOM];[warn];[crit];[min];[max]
Table 1 Performance parts with descriptions.
Part
Description
label
The label can contain any characters. If space is included quotes are needed.
value
The plugin was able to check the service, but it appeared to be above some "warning" threshold or did not appear to be working properly
UOM
Can be any of:
no unit assuming an integer as a value
s - seconds (also us, ms)
% - percentage.
B- Bytes (also KB, MB, GB and TB)
c - A continuous counter like bytes transmitted on an interface.
warn, crit, min, max
Can all be null and trailing unfilled semicolons can be dropped.
min and max is not needed if UOM is %.
value, warn, crit, min and max must be of the same UOM.
 
 
Example 2 Performance data output
time=0.218901s;;;0.000000 size=42236B;;;0
 
The Example 2 on page 93 shows a performance data output from a plugin with two values separated with one space in the output.
Return code
The return code is the one that op5 Monitor uses to determine what state the services is in. It may be one of the following:
0, 1, 2, 3
Any return code above 0 is to be known as problem states.
Table 2 The return codes in detail.
Nr
Name
Description
0
Ok
The check did ok and everything seems to be working fine.
1
Warning
The plugin was able to check the service, but it appeared to be above some "warning" threshold or did not appear to be working properly
2
Critical
The plugin detected that either the service was not running or it was above some "critical" threshold
3
Unknown
Something unknown happened during the check. Things like invalid command line arguments or low-level failures internal to the plugin shall not be reported as Unknown state.
Adding your first plugin to op5 Monitor
In this section we will create a very simple plugin. We will write it as a bash script in a ssh connection to the op5 Monitor server.
This plugin will not actually be very useful but we will use it to describe the steps needed when you starts to add other more useful plugins.
Creating the plugin
To create a simple example plugin as a bash script
1 cd /opt/plugins/custom
touch helloworld
chmod 755 helloworld
2 Open up the script with your favorite text editor and type in the following example plugin:

#!/bin/sh
echo 'WARNING: Hello world!'
exit 1
3 Save and exit your editor
4 Execute it from the terminal:
5 ./helloworld
WARNING: Hello world!
echo $?
1
The script prints the status output (WARNING: Hello world!).
echo $? prints the return code of the last executed command.
Configuring op5 Monitor to use the plugin
To configure op5 Monitor to use the plugin
1 Go to Configure and choose Commands.
2 Add a new command with:
command_name: check_local_helloworld
command_line: $USER1$/custom/helloworld
3 Click Apply and then Save.
 
Now you may use your check command with a service.
Creating a more complex plugin
In this section we will create a more complex and useful plugin compared to the one we created in Adding your first plugin to op5 Monitor on page 95. We will stick to bash, because of the simplicity
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.
To create a more complex plugin
1 Create the script and editing it:
cd /opt/plugins/custom
touch check_op5backup
chmod 755 check_op5backup
2 Open up the script with your favorite text editor and type in the following code:

#!/bin/bash
# Create a function to print the storage path
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
3 Add a check_command like this using the op5 Monitor web gui:
command_name: check_op5backup
command_line: $USER1/custom/check_op5backup
4 Enter the service configuration for your monitor server, and add a service with check_op5backup as the check_command.
5 Save configuration.
More information
This chapter has only scratched on the surface of how to write your own plugins.
To read more about plugin development take a look at the Nagios plugin development guidelines:
http://nagiosplug.sourceforge.net/developer-guidelines.html