Pandora: Documentation en: Anexo Server plugins developement

From Pandora FMS Wiki
Revision as of 09:35, 17 July 2020 by Sergio.gomez (talk | contribs) (Header/Definition)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Go back to Pandora FMS documentation index

Template wip.png

We are working on the translation of the Pandora FMS documentation. Sorry for any inconvenience.


1 Servers Plugin Development

1.1 Basic Features of the Server Plugin

The plugin server is executed by the Pandora FMS Server Plugin , so it should have a very specific features:

  • Every execution of the plugin should return a single value. This should be like this, because the Server Plugin makes an execution by each module type plugin.
  • It should have access to the resources to monitor in a remote way.
  • It is possible to use any programming language that supports the operative system where the Pandora server is installed
  • All dependencies or necessary software to execute the plugin should be available or be installed in the same machine that executes the Pandora server.

1.2 Example of Server Plugin Development

Next we are going to describe a possible example of server plugin for Pandora FMS.

The following plugin returns the sum of the entry and exit traffic of a device interface. Data are got through SNMP.

The plugin code would be this:

#!/usr/bin/perl -w

use strict;
use warnings;

sub get_param($) {
        my $param = shift;
        my $value = undef;

        $param = "-".$param;

        for(my $i=0; $i<$#ARGV; $i++) {

                if ($ARGV[$i] eq $param) {
                        $value = $ARGV[$i+1];

        return $value;

sub usage () {
        print " version v1r1\n";
        print "\nusage: $0 -ip <device_ip> -community <community> -ifname <iface_name>\n";
        print "\nIMPORTANT: This plugin uses SNMP v1\n\n";

#Global variables
my $ip = get_param("ip");
my $community = get_param("community");
my $ifname = get_param("ifname");

if (!defined($ip) ||
        !defined($community) ||
        !defined($ifname) ) {

#Browse interface name
my $res = `snmpwalk -c $community -v1 $ip . -On`;

my $suffix = undef;

my @iface_list = split(/\n/, $res);

foreach my $line (@iface_list) {

        #Parse snmpwalk line
        if ($line =~ m/^([\d|\.]+) = STRING: (.*)$/) {
                my $aux = $1;

                #Chec if this is the interface requested
                if ($2 eq $ifname) {

                        my @suffix_array = split(/\./, $aux);

                        #Get last number of OID
                        $suffix = $suffix_array[$#suffix_array];

#Check if iface name was found
if (defined($suffix)) {
        #Get octets stats
        my $inoctets = `snmpget $ip -c $community -v1 .$suffix -OUevqt`;
        my $outoctets = `snmpget $ip -c $community -v1 .$suffix -OUevqt`; 

        print $inoctets+$outoctets;

An important part of the code is the usage function:

sub usage () {
        print " version v1r1\n";
        print "\nusage: $0 -ip <device_ip> -community <community> -ifname <iface_name>\n";
        print "\nIMPORTANT: This plugin uses SNMP v1\n\n";

In this function it describes the version and how to use the plugin. It is very important and always should be shown when executing the plugin without any type of parameter or also with an option type -h or --help.

Concerning to the value that the plugin has returned, this is printed in the standard output of the second to last line with the following instruction:

print $inoctets+$outoctets;

As you can see the value returned by the plugin is a single data, that after the Pandora Server Plugin will add as data to the associated module.

To could execute this server plugin, you should install the commands snmpwalk and snmpget in the machine that the Pandora server executes.

1.3 Plugin manual registration

Registro manual plugin.png

  • Name

Name of the plugin.

  • Plugin type

There are two kinds of plugins, the standard ones and the kind Nagios. The standard plugins are scripts that execute actions and accept parameters. The Nagios plugins are, as their name shows, Nagios plugins that could be being used in Thor. The difference is mainly on that the Nagios plugins return an error level to show if the test has been successful or not.

If you want to use a plugin kind Nagios and you want to get a data, not an state (Good/Bad), then you can use a plugin kind Nagios is the "Standard" mode.

  • Max. timeout

It is the time of expiration of the plugin. If you do not receive a response in this time, you should select the module as unknown, and its value will be not updated. It is a very important factor when implementing monitoring with plugins, so if the time it takes at executing the plugin is bigger than this number, we never could obtain values with it. This value should always be bigger than the time it takes usually to return a value the script/executable that is used as plugin. In there is nothing said, then you should used the value that in the configuration is named plugin_timeout.

  • Plug-in command

It is the path where the plugin command is. In a default way, if the installation has been an standard one, there will be in the directory /usr/share/pandora_server/util/plugin/. Though it could be any path of the system. For this case, write /usr/share/pandora_server/util/plugin/ in the field.

The server will execute this script, so this should have permissions of access and execution on it.

  • Plug-in parameters

A string with the parameters of the command that will be after command and a blank space. This parameters field accepts macros as _field1_ _field2_ ... _fieldN_.

  • Parameters macros

Is possible to add unlimited macros to use it in Plug-in parameters field. This macros will appear as normal text fields in the module configuration.

1.4 Packaging in PSPZ

1.4.1 Pandora Server Plugin Zipfile (.pspz)

With Pandora FMS 3.0 there is a new way to register plugins and modules who uses the new Plugin (like a library of modules depending on the plugin). This is basically an admin extension to upload a file in .pspz format who is described below. System reads the file, unpack and install the binaries/script in the system, register the plugin and create all the modules defined in the .pspz in the module library of Pandora FMS (Network components).

This section describe how to create a .pspz file.

1.4.2 Package File

A .pspz is a zip file with two files:

plugin_definition.ini: Who contains the specification of the plugin and the modules. Should have this name (case sensitive).

<script_file>: It's the plugin script/binary itself. Could have any valid name. You can download an example of .pspz here.

1.4.3 Structure of plugin_definition.ini Header/Definition

This is a classic INI file with optional sections. The first section, the most important, is a fixed name section called "plugin_definition", and this is an example:

name = Remote SSH exec
filename =
description = This plugin execute remotely any command provided
timeout = 20
ip_opt = -h
execution_command = 
execution_postcommand = 
user_opt = -u
port_opt = 
pass_opt = 
plugin_type = 0
total_modules_provided = 1

filename: Should have the same name as the script included in the .pspz file, referenced before as <script_file>. In this sample is a .sh shell script called "".

*_opt: Are the registration options for the plugin, like shown in the form to register "manually" the plugin in the Pandora FMS console.

plugin_type: 0 for a standard Pandora FMS plugin, and 1 for a Nagios-type plugin.

total_modules_provided: It specifies how many modules are defined below. At least one must be set (to use at least in an example).

execution_command: If used, put this before the script. Could be a interpreter, like for example "java -jar". So plugin will be called from Pandora FMS Plugin Server as "java -jar <plugin_path>/<plugin_filename>".

execution_postcommand: If used, defines aditional parameters passed to the plugin after the plugin_filename , invisible for the user. Module definition / Network components

This are defined as dynamic sections (section with an incremental name), and you may have many as you want, and you need to define here the same number of modules as defined in total_modules_provided in prev. section. If you have 4 modules, section names should be module1, module2, module3 and module4.

This is an example of a module definition:

name = Load Average 1Min
description = Get load average from command uptime
id_group = 12
type = 1
max = 0
min = 0
module_interval = 300
id_module_group = 4
id_modulo = 4
plugin_user = root
plugin_pass = 
plugin_parameter = "uptime | awk '{ print $10 }' | tr -d ','"
max_timeout = 20
history_data = 1
min_warning = 2
min_critical = 5
str_warning = "peligro"
min_critical = "alerta"
min_ff_event = 0
tcp_port = 0
critical_inverse = 0
warning_inverse = 0
critical_instructions = "Call head of department"
warning_instructions = "Calling the server manager to reduce the load"
unknown_instructions = "Verify that Pandora FMS agent is running"

A few things to have in mind:

  • Do not "forget" any field, all fields *MUST* be defined, if you don't have data, let it blank, like the plugin_pass field in the example above.
  • Use double quotes "" to define values who contains special chars or spaces, like the field plugin_parameter in the above example. INI files who contains characters like ' " / - _ ( ) [ ] and others, MUST have double quotes. Try to avoid use of character " in data, if you must use it, escape with \" combination.
  • If you have doubts on the purpose or meaning of this fields, take a look on tnetwork_component in your Pandora FMS database, it has almost the same fields. When you create a network component is stored in that database, try to create a network component who use your plugin and analyze the record entry in that table to understand all the values.
  • id_module, should be 4 always (this means this is a plugin module).
  • type, defines what kind of module is: generic_data (1), generic_proc (2), generic_data_string (3) or generic_data_inc (4) as defined in ttipo_modulo.
  • id_group, is the PK (primary key) of the tgrupo table, who contain group definitions. Group 1 is "all groups", and acts like an special group.
  • id_module_group, comes from table tmodule_group, just an association of module by functionality, purely descriptive. You can use "1" for General module group.

1.4.4 Version 2

From Pandora FMS v5.1.SP1, The server plugins use macros.

Template warning.png

These plugins differentiated by the extension of the .pspz2 file.


Besides, plugin_definition.ini has changed. The following fields are added:

In section plugin_definition:

  • total_macros_provided That defines the number of dynamic macros that the plugin has.

In section module<N>:

  • macro_<N>_value that defines the value for this module using this dynamic macro. It it doesn't exist it gets the default value.

And then, for each dynamic macro, a new section will be created, just like this:

hide = 0
description = descripción
help = texto de ayuda
value = valor

This new structure is which we know as version 2.


You must explicitly call the macro substitution (_fieldx_) in section execution_postcommand', see example below



The previous version is still compatible. If the version parameter is not defined, then we assume that the version is version 1 Example of a v2 (.pspz2) plugin definition

name = PacketLoss
filename =
description = "Measure packet loss in the network in %"
timeout = 20
ip_opt = 
execution_command = 
execution_postcommand = 
parameters = _field1_ _field2_
user_opt = 
port_opt = 
pass_opt = 
plugin_type = 0
total_modules_provided = 1
total_macros_provided = 2

hide = 0
description = Timeout
help = Timeout in seconds
value = 5

hide = 0
description = Target IP
help = IP adddress
value =

name = Packet loss
description = "Measure target packet loss in % "
id_group = 15
type = 4
max = 0
min = 0
module_interval = 300
id_module_group = 2
id_modulo = 1
max_timeout = 20
history_data = 1
min_warning = 30
min_critical = 40
min_ff_event = 0
tcp_port = 0
macro_1_value = 5
macro_2_value = localhost
unit = %

2 Upgrade a old PSPZ (Pandora version 4)

Some PSPZ are before of the dinamic parameters for server plugins and these PSPZ had a fixed parameters, it is not running in new pandora versions. For to fix there is a procedude in:

Upgrading from Previous Versions >> Updating to a Major Version >> Update from Version 4.x to 5.0 >> Plug Ins

Go back to Pandora FMS documentation index