Custom plugins

Fabio Martins
September 14, 2017

This post is the first of a series of tutorials about plugin development for the Unit Platform. The next posts will talk about how to load a plugin into the Unit Plaform, how to extract data from SNMP, and how to use a custom plugin with Netwall Direct Agent.

What’s a plugin?

Plugins are scripts or compiled programs that perform the gathering of specific information about a device, service, application or protocol.

Plugin customization is necessary when the tool’s pre-registered plugins do not meet the needs. In this case plugin customization is a must do.

Where do plugins run?

Plugins can run locally on the Unit Platform or in remote Windows and Linux servers, provided they have the Netwall Direct Agent installed.

Plugins are triggered by the monitoring service of the Multisite Monitoring product, whether they’re running on-premises or on remote servers.

With what technologies can plugins be developed?

If the plugin is designed to run locally on the Unit Platform, we recommend using the following technologies:

Bash

  • Version 4.1.2
  • Executable path: /bin/bash

Perl

  • Version 5.10.1
  • Executable path: /usr/bin/perl

Python

  • Version 2.7.11
  • Executable path: /opt/3rdparty/python27/bin/python

PHP

  • Version 5.6.11
  • Executable path: /usr/bin/php

Awk

  • Version 3.1.7
  • Executable path: /bin/awk

Executable

  • Distribution CentOS 6.5 x64

If the plugin is designed to run on remote servers, any technology can be used as long as the server supports it. Here are the most used technologies:

Linux

  • Bash
  • Perl
  • Python
  • C/C++
  • Java

Windows

  • Powershell
  • VBScript
  • Java
  • C/C++
  • Batch file (.bat)

How are the input and output patterns of the plugins?

For plugins to be supported by Multisite Monitoring there are some standards to be followed.

Argument Input

The first requirement is the input standards. All the arguments that need to be passed to the plugin must be declared on the command line. Here are some examples:

plugin_1 [argument1] [argument2] [argument3]
plugin_2 -n [argument1] -i [argument2] -c [argument3]
plugin_3 --name [argument1] --id [argument2] --compare [argument3]

In the examples above, three different and valid formats were displayed.

In the first example, plugin_1, the arguments are declared in a mandatory sequential form without identification.

In the second and third examples, the arguments are not sequences, and they’re all optional. What differs these last two are the short and extended declarations. This pattern is advised in scripts running on Linux systems (in the example, -n e --name are identical).

Another very common practice is to add two options to the plugin, one for version and one for debug, as shown below:

  • Version: -v or --version
  • Debug: -d or --debug

Plugin Output

The second step that must be followed is the output rules. The plugin should only print the results on a single line. In order to make the personalization of the monitoring rules as flexible as possible, the Unit Platform requires a specific format for data output. Every plugin must print the results on a single line and follow the format below:

[auxiliary strings]|[results]

The auxiliary strings are used to compose the messages the services will show on the product’s interface, while the results are the data Multisite Monitoring is going to use to define the status of a service and to show the performance graphs. Note that what separates the strings from the results is the “|” character. The auxiliary strings are optional, and in case the plugin does not use it, this “|” character won’t be necessary, and the whole string will be considered as a “result”.

Both sides of the “|” support multiple values. In that case, all values must be separated by the character “;”.

Below are some examples of outputs that don’t make use of the auxiliary strings:

35.91
0.27;0.45;0.29
Welcome
Google Search;I’m felling lucky

Observation: the results, in case more than one is used, are required to be of the same type and measurement unit.

These are the result types supported at the moment:

  • Text: any set of words. The characters “|”, “;” e “!” are not allowed and must not be used.
  • Number: In this case it shouldn’t have the measurements, just the raw number. And if the value is fractional, the decimal separator should be the “.”.

Plugins that return numeric results will have a performance graph associated with them. Plugins that output text as results will not have graphs.

Below are some examples of outputs that use the auxiliary strings:

C:/|142080884
In;Out|12;18
Firefox.exe|17

The plugin must exit with exitcode 0. If it’s any different than this, the result won’t be processed.

How do I make my first plugin?

In this topic, we’ll explain how to create your first plugin running on the Unit Platform. This example of plugin aims to collect the temperature of a city and to display some additional information.

For the execution of this plugin, the Unit Platform must have internet access through the HTTP port to collect the information via WebService.

At your workstation, create a file with the PHP extension, which is the language we’ll use as a first example. The file will be called my_first_plugin.php. Copy the code below into the file and save it.

#!/usr/bin/php
<?php

$cid = $argv[1];
$dados = json_decode(file_get_contents('http://api.hgbrasil.com/weather/?cid='.$cid.'&format=json'), true);

echo $dados['results']['city_name'].";".$dados['results']['description'].";".$dados['results']['humidity'].";".$dados['results']['wind_speedy']."|".$dados['results']['temp'];
?>

If executed on a terminal, this script’s output should show something very similar to this example:

Porto Alegre;Ensolarado;77;11.27 km/h|18

As mentioned before, the auxiliary strings are separated by “;” and the result is located after the “|”. The additional texts are respectively “City Name”, “Weather Forecast Description”, “Humidity” and “Wind Speed”. The result is only “Temperature”.

Another detail that should be noted is the script header #!/usr/bin/php. On Linux it’s necessary to add the path of the executable in the first line of the script, because the extension “.php” in Linux is only for organization reasons, other than on Windows where the executable is related to file extension.

Keep in mind that running on the command line is not necessary, it is only informative in this document. If you want to run this particular plugin outside the Unit Platform, you must have PHP installed on your machine.

Now we go to the second part of this tutorial: loading and using the plugin on the Platform.