Pandora:Documentation en:Anexo Server plugins developement

From Pandora FMS Wiki

Jump to: navigation, search

Go back to Pandora FMS documentation index

Servers Plugin Development

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.

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];
                        last;
                }

        }
        return $value;
}

sub usage () {
        print "iface_bandwith.pl 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) ) {
        usage();
        exit;
}

#Browse interface name
my $res = `snmpwalk -c $community -v1 $ip .1.3.6.1.2.1.2.2.1.2 -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 .1.3.6.1.2.1.2.2.1.10.$suffix -OUevqt`;
        my $outoctets = `snmpget $ip -c $community -v1 .1.3.6.1.2.1.2.2.1.16.$suffix -OUevqt`; 

        print $inoctets+$outoctets;
}

An important part of the code is the usage function:


sub usage () {
        print "iface_bandwith.pl 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.

Packaging in PSPZ

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.

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]

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:

[plugin_definition]
name = Remote SSH exec
filename = ssh_pandoraplugin.sh
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 "ssh_pandoraplugin.sh".

*_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: Defines how many modules are defined below. You should define at least one (for use as example as minimum).

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 a 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:

[module1]
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 the boss"
warning_instructions = "Call NASA"
unknown_instructions = "I want a pizza and maybe beer"


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.

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:

[macro_<N>]
hide = 0
description = descripción
help = texto de ayuda
value = valor

This new structure is which we know as version 2.

Info.png

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

 


Info.png

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

[plugin_definition]
name = PacketLoss
filename = packet_loss.sh
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

[macro_1]
hide = 0
description = Timeout
help = Timeout in seconds
value = 5

[macro_2]
hide = 0
description = Target IP
help = IP adddress
value = 127.0.0.1

[module1]
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 = %

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