Pandora: Documentation es: Anexo Server Plugins

From Pandora FMS Wiki
Jump to: navigation, search

Volver a Indice de Documentacion Pandora FMS

1 Desarrollo de plugins del servidor

1.1 Características básicas de plugin de servidor

El plugin de servidor es ejecutado por el Plugin Server de Pandora FMS por lo que tiene que tener unas características especiales:

  • Cada ejecución del plugin deberá devolver un único valor. Esto debe ser así ya que el Plugin Server realiza una ejecución por cada módulo de tipo plugin.
  • Debe poder acceder a los recursos a monitorizar de forma remota.
  • Es posible usar cualquier lenguaje de programación que soporte el sistema operativo donde está instalado el servidor de Pandora.
  • Todas las dependencias o software necesario para ejecutar el plugin deberá estar disponible o ser instalado en la misma máquina que ejecuta el servidor de Pandora.

1.2 Ejemplo desarrollo plugin de servidor

A continuación se describe un ejemplo posible de plugin de servidor para Pandora FMS.

El siguiente plugin devuelve la suma del tráfico de entrada y salida de una interfaz de un dispositivo, los datos se obtienen por SNMP.

El código del plugin sería el siguiente:

#!/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;
}

Una parte importante del código es la función usage:

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";
}

En esta función describe la versión y cómo usar el plugin, es muy importante y siempre se debe mostrar al ejecutar el plugin sin ningún tipo de parámetro o bien con una opción tipo -h o --help.

Respecto al valor que devuelto el plugin, este se imprime en la salida estándar en la penúltima línea con la siguiente instrucción:

print $inoctets+$outoctets;

Como se puede ver el valor devuelto por el plugin es un único dato, que luego el Plugin Server de Pandora añadirá como dato al módulo asociado.

Para poder ejecutar este plugin de servidor será necesario instalar los comandos snmpwalk y snmpget en la máquina que ejecuta el servidor de Pandora.

1.3 Empaquetado en PSPZ

1.3.1 El Plugin Zipfile (.pspz) del Servidor de Pandora

Desde Pandora FMS 3.0 existe una nueva manera de registrar plugins y módulos que usan el nuevo plugin (como por ejemplo la librería de módulos que depende del plugin). Es, básicamente, una extensión de administrador para subir un fichero en formato .pspz, que está descrito más abajo. El sistema lee el fichero, lo desempaqueta e instala los binarios/script en el sistema. Además registra el plugin y crea todos los módulos definidos en el .pspz en la librería de módulos de Pandora FMS (componentes de red).

Esta sección describe cómo crear un fichero .pspz.

1.3.2 Package File

Un .pspz es un fichero zip con dos filas:

plugin_definition.ini: contiene la especificación del plugin y de los módulos. Deberá tener este nombre (es case sensitive).

<script_file>: es el plugin script/binary en sí. Podrá tener cualquier nombre válido. Un ejemplo de un fichero .pspz (renombrado como .zip) se puede descargar de: [1]

1.3.3 Estructura de plugin_definition.ini

1.3.3.1 Cabecera/Definición

Este es un fichero INI clásico con secciones opcionales. La primera sección, que es la más importante, es una sección de nombre fijo llamada "plugin_definition". Este es un ejemplo:

[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: debería tener el mismo nombre que el script incluido en el fichero .pspz, nombrado antes como <script_file>. En este ejemplo es un shell script .sh llamado "ssh_pandoraplugin.sh".

*_opt: aquí están las opciones de registro del plugin, mostradas en el formulario para registrar "manualmente" el plugin en la consola de Pandora FMS.

plugin_type: 0 para un plugin estandar de Pandora FMS, y 1 para un plugin tipo Nagios.

total_modules_provided: define cuantos módulos se definen abajo. Debe definir uno como mínimo (para usar en un ejemplo como mínimo).

execution_command: si se emplea, hay que ponerlo delante del script. Podrá ser un intérprete, como por ejemplo "java -jar". Así pues, el plugin se llamará, desde el Plugin Serever de Pandora FMS: "java -jar <plugin_path>/<plugin_filename>".

execution_postcommand: si se emplea, define los parámetros adicionales transmitidos al plugin después del plugin_filename, que es invisible para el usuario.

1.3.3.2 Definición del Modulo / Componentes de Red

Estas se definen como secciones dinámicas (secciones con un nombre incremental), y puede tener tantas como quiera. Necesitará definir aquí el mismo número de módulos que los definidos en total_modules_provided de la sección anterior. Si tiene por ejemplo 4 módulos, los nombres de las secciones deberán ser: módulo1, módulo2, módulo3 y módulo4.

Este es un ejemplo de una definición de módulo:

[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 = "Llamar al jefe"
warning_instructions = "Llamar a la NASA"
unknown_instructions = "Pedir una pizza"

Algunas cosas que deberá tener en cuenta son:

  • No "olvide" ningún campo. Todos los campos *DEBEN* estar definidos. Si no dispone de datos, déjelo en blanco, como el campo plugin_pass del ejemplo de arriba.
  • Utilize dobles comillas "" para definir valores que contengan carácteres especiales o espacios, como el campo plugin_parameter del ejemplo de arriba. Los ficheros INI que contengan caracteres como ' "/ -_ ( ) [ ] y otros, DEBEN tener dobles comillas. Intente evitar el uso del carácter " para los datos. Si debe emplearlo, escape con la combinación \" .
  • Si tiene dudas sobre el propósito o significado de estos campos, eche un vistazo al tnetwork_component de su base de datos de Pandora FMS.Esta tiene casi los mismos campos. Cuando se crea un nuevo componente de red, este es almacenado en esta base de datos. Intente crear un componente de red que utilize su plugin y analize el registro de entrada en esa tabla para entender todos los valores.
  • id_module, deberá ser siempre 4 (esto significa que es un módulo plugin)
  • type, define que tipo de módulo es: generic_data (1), generic_proc (2), generic_data_string (3) o generic_data_inc (4) tal y como fueron definidos en ttipo_modulo
  • id_group,es la PK (primary key) de la tabla tgrupo que contiene definiciones de grupo. EL grupo 1 es "todos los grupos", y actua como un grupo especial.
  • id_module_group,procede de la tabla tmodule_group. Es una asociación de módulo por funcionalidad, puramente descriptiva. Puede usar "1" para el General module group.

1.3.4 Versión 2

A partir de Pandora FMS v5.1.SP1, los plugins de servidor utilizan macros.

Template warning.png

Se diferenciaran estos plugins por la extensión del fichero pspz2. Si no tiene esta extensión se asumirá una PSPZ de tipo 1 (sin macros dinámicas en la extension de Plugin remoto)

 


Además plugin_definition.ini ha cambiado. Se ha añadido los siguientes campos:

En la sección plugin_definition:

  • total_macros_provided que define el numero de macros dinámicas que tiene el plugin.

En la sección module<N>:

  • macro_<N>_value que define el valor para ese módulo usando esa macro dinámica, si no existe se toma el valor por defecto.

Y se creará una sección por cada macro dinámica tal que así:

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

Esta nueva estructura se conoce como la versión 2.

Info.png

Debe llamar en la seccion execution_postcommand' a los macros para que se realice la substitucion (ver ejemplo)

 


Info.png

La versión anterior sigue siendo compatible. Si el parámetro versión no está definido, se asume que la versión es 1

 


1.3.4.1 Ejemplo de definición de un plugin v2 (.pspz2)

[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 = 10
type = 1
max = 0
min = 0
module_interval = 300
id_module_group = 2
id_modulo = 4
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 Actualización de un PSPZ antiguo (Pandora versión 4)

Algunos PSPZ son de antes de los campos dinámicos de parámetros para los plugins y tenían parámetros fijos, no funcionan en versiones nuevas. Para migrarlos hay un procedimiento en:

Actualizar desde una version anterior >> Actualizar una versión mayor >> Notas de actualización desde la versión 4.x a la 5.0 >> Plugins

Volver a Indice de Documentacion Pandora FMS