Servers Plugin Développement

Le serveur plugin est exécuté par le Plugin Server de Pandora FMS, il doit donc présenter certaines caractéristiques particulières:

• Chaque exécution de plugin renvoie une seule valeur. Cela doit être le cas puisque le Plugin Server PFMS effectue une exécution par module de type plugin.
• Il doit pouvoir accéder à distance aux ressources à superviser.
• Il est possible d'utiliser n'importe quel langage de programmation supporté par le système d'exploitation où le PFMS Server est installé.
• Toutes les dépendances ou logiciels nécessaires à l'exécution du plugin doivent être disponibles ou installés sur la même machine que celle sur laquelle tourne le PFMS Server.

Pour plus d'informations sur la supervision à l'aide de plugins serveur distant, veuillez consulter ce lien. Vous y trouverez des exemples simples et la manière dont ils fonctionnent avec les modules et les agents qui les contiennent. Cet article examine en détail la création du serveur plugin.

Le plugin suivant renvoie la somme du trafic entrant et sortant sur l'interface d'un appareil, les données étant obtenues par SNMP.

Le code du plugin est le suivant:

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

Une partie importante du code est la fonction 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";
}

Cette fonction décrit la version et la manière d'utiliser plugin, elle est très importante et devrait toujours être affichée lors de l'exécution de plugin sans aucun paramètre ou avec une option -h ou:

--help

La valeur renvoyée par plugin est imprimée sur la sortie standard à l'avant-dernière ligne avec l'instruction suivante:

print $inoctets+$outoctets;

La valeur renvoyée par le plugin est une donnée unique, que le Plugin Server PFMS ajoutera ensuite en tant que données au module associé.

Afin d'exécuter ce serveur plugin, il est nécessaire d'installer les commandes snmpwalk et snmpget sur la machine qui exécute le PFMS Server.

Menu Management → Servers → Plugins → Add plugin.

• Plugin type:

La principale différence avec PFMS est que les plugins de Nagios renvoient un niveau d'erreur pour indiquer si le test a réussi ou non. Si vous avez besoin de données, et non d'un état (bon/mauvais), vous pouvez utiliser un plugin Nagios en mode « Standard » (pour MS Windows® est utilisé Nagios wrapper for agent plugin).

• Max. timeout:

Il s'agit de l'heure d'expiration du complément. Si aucune réponse n'est reçue dans ce délai, le module sera marqué comme inconnu et sa valeur ne sera pas mise à jour. Il s'agit d'un facteur très important lors de la mise en œuvre de la supervision avec des plugins, car si le temps nécessaire à l'exécution du plugin est supérieur à ce nombre, vous ne pourrez jamais obtenir de valeurs de ce dernier. Cette valeur doit toujours être supérieure au temps normalement nécessaire pour que le script ou l'exécutable utilisé comme plugin renvoie une valeur. Si rien n'est spécifié, la valeur spécifiée dans la configuration comme plugin_timeout sera utilisée.

• Plug-in command:

Il s'agit du chemin où se trouve la commande du module complémentaire. Par défaut, si l'installation a été standardisée, ils seront dans le répertoire:

/usr/share/pandora_server/util/plugin/

Cependant, il peut s'agir de n'importe quel chemin dans le système.

Dans ce cas, tapez /usr/share/pandora_server/util/plugin/udp_nmap_plugin.sh dans le champ.

Le serveur exécutera ce script, il doit donc disposer de permissions d'accès et d'exécution.

• Plug-in parameters:

Une chaîne contenant les paramètres plugin, qui suivront la commande et un espace vide. Ce champ accepte des macros telles que _field1_ _field2_ … _fieldN_. La section suivante explique le fonctionnement des macros.

• Parameters macros:

Il est possible d'ajouter un nombre illimité de macros à utiliser dans le champ de paramètre plugin. Ces macros apparaissent comme des champs de texte dans la configuration du module. La section suivante explique le fonctionnement des macros.

Prenons l'exemple du DNS Plugin installé par défaut sur un serveur Pandora FMS.

Ce module complémentaire permet à un domaine web et à son adresse IP correspondante d'être vérifiés par un serveur de résolution de domaine (serveur DNS).

• -i: Adresse IP connue du domaine.
• -d: Domaine web correspondant.
• -s: Serveur DNS à interroger.

Connaissant ces trois paramètres, procédez à l'enregistrement manuel d'un nouveau plugin, en le nommant New DNS Plugin et dans la description copiez le résumé précédent et indiquez également qu'il est nécessaire pour le module de collecter une valeur fausse (zéro) ou vraie (un) pour la supervision. Ce type de données est également connu sous le nom de boolean et, dans Pandora FMS, il est appelé generic_proc.

Dans la section des paramètres macro (Paramètres macro), ajoutez trois champs macro field1, field2 et field3.

Pour _field1_, placez la description correspondant au paramètre -i et ainsi de suite pour les paramètres -d et -s. Laissez les valeurs par défaut (default value) vides, écrivez dans l'aide (help) de chacune d'elles le texte que vous jugez approprié.

Dans la zone de texte Plugin command, tapez:

/usr/share/pandora_server/util/plugin/dns_plugin.sh

Dans la zone de texte Paramètres du plugin, tapez:

-i _field1_ -d _field2_ -s _field3_

/usr/share/pandora_server/util/plugin/dns_plugin.sh -i _field1_ -d _field2_ -s _field3_

De la même manière que _field1_, _field2_, (…), _fieldN_, les macros fonctionnent également, à ceci près qu'elles contiennent des valeurs spéciales à la fois pour les modules et pour les agents qui contiennent ces modules.

Reprendre l'exemple de la section précédente où les valeurs par défaut du _fieldN_ ont été laissées vides. Modifier et pour la valeur par défaut de _field2_ placer la macro _module_.

Cette macro _module_ renvoie le nom du Module utilisé par le plugin et sera défini à l'utilisateur ou à la politique lors de la création du Module. Pour le vérifier, créez un nouvel agent appelé DNS verify et ajoutez un nouveau module à l'aide de l'option Create a new plugin server module.

Lorsque vous entrez dans le formulaire d'édition du nouveau module, dans Plugin, sélectionnez dans la liste New DNS Plugin et la macro _module_ apparaîtra comme suit:

N'oubliez pas de définir le type de données à collecter sur Generic boolean et, pour le nom du nouveau module, définissez le domaine web à vérifier pour son adresse IP correspondante par rapport à un serveur DNS spécifié. La fonction token critical_on_error du serveur PFMS est configurée par défaut pour que les modules dont l'état est inconnu deviennent critiques. Stockez et vérifiez son fonctionnement.

• _agent_: Alias de l'agent à utiliser dans la macro. Si aucun alias n'est attribué, le nom de l'agent sera utilisé.
• _agentalias_: Alias de l'agent à utiliser dans la macro.
• _agentdescription_: Description de l'agent à utiliser dans la macro.
• _agentstatus_: État actuel de l'agent lorsqu'il est utilisé dans la macro.
• _agentgroup_: Nom du groupe d'agents qui doit utiliser la macro.
• _agentname_: Nom de l'agent à utiliser dans la macro (voir aussi _agent_).
• _address_: Adresse de l'agent qui doit utiliser la macro.
• _module_: Nom du module dans lequel la macro doit être utilisée.
• _modulegroup_: Nom du groupe de modules dans lequel la macro doit être utilisée.
• _moduledescription_: Description du module d'utilisation de la macro.
• _modulestatus_: État du module à utiliser par la macro.
• _moduletags_: URLs associées aux tags des modules.
• _id_module_: Identifiant du module à utiliser par la macro.
• _id_agente_: Identifiant de l'agent qui utilise la macro, utile pour créer des URL permettant d'accéder à la console de Pandora FMS.
• _id_group: Identifiant du groupe d'agents à utiliser par la macro.
• _interval_: Intervalle d'exécution du module pour l'utilisation de la macro.
• _target_ip_: Adresse IP de la cible du module à utiliser par la macro.
• _target_port_: Port de la cible du module pour l'utilisation de la macro.
• _policy_: Nom de la police à laquelle le module appartient (le cas échéant).
• _plugin_parameters_: Paramètres de l'extension du module à utiliser par la macro.
• _email_tag_: Boîtes aux lettres électroniques associées aux balises (tags) des modules.
• _phone_tag_: Téléphones associés aux tags des modules.
• _name_tag_: Nom des balises associées au module à utiliser par la macro.

Il existe un moyen d'enregistrer les plugins et les modules qui utilisent le nouveau plugin (comme la bibliothèque de modules qui dépend du plugin). Il s'agit essentiellement d'une extension d'administrateur permettant de télécharger un fichier au format .pspz, décrit en détail dans les sections suivantes. Le système lit le fichier, décompresse et installe les binaires et/ou les scripts dans le système. En outre, il enregistre le plugin et crée tous les modules définis dans le .pspz dans la bibliothèque de modules de Pandora FMS (composants réseau).

Cette section décrit comment créer un fichier .pspz.

Un .pspz est un fichier compressé au format zip avec deux lignes:

plugin_definition.ini : Contient la spécification du plugin et du module. Il doit avoir exactement ce nom (il est case sensitive, sensible à la casse).

< script_file > : Il s'agit du plugin script binary (script de commande ou code binaire exécutable) lui-même. Il peut avoir n'importe quel nom valide. Un exemple de fichier .pspz (lui-même compressé en .zip pour inclure sa documentation) peut être téléchargé à ce lien.

Il s'agit d'un fichier INI classique avec des sections optionnelles. La première section, qui est la plus importante, est une section à nom fixe appelée plugin_definition. Voici un exemple:

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

filename: Il doit porter le même nom que le script inclus dans le fichier .pspz, nommé auparavant comme < script_file >. Dans cet exemple, il s'agit d'un script shell (format .sh) nommé ssh_pandoraplugin.sh.

_opt: Voici les options d'enregistrement du plugin, présentées dans le formulaire d'enregistrement « manuel » du plugin dans la Console de Pandora FMS.

plugin_type: 0 pour un plugin standard de Pandora FMS, et 1 pour un plugin Nagios.

total_modules_provided: Il spécifie combien de modules sont définis dans les sections suivantes du fichier .ini. Vous devez en définir au moins un (à utiliser dans au moins un exemple).

execution_command: S'il est utilisé, il doit être placé devant script. Il peut s'agir d'un interpréteur, tel que java -jar. Ainsi, le plugin sera appelé à l'exécution, depuis le Plugin Server PFMS, avec le code suivant:

java -jar <plugin_path>/<plugin_filename>

execution_postcommand: S'il est utilisé, il définit les paramètres supplémentaires transmis à plugin après la commande < plugin_filename >, qui est invisible pour l'utilisateur.

Si vous avez par exemple quatre modules, les noms des sections doivent être: module1, module2, module3 et module4.

Il s'agit d'un exemple de définition de module:

[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 = "danger"
min_critical = "alert"
min_ff_event = 0
tcp_port = 0
critical_inverse = 0
warning_inverse = 0
critical_instructions = "Call the department head"
warning_instructions = "Call the server manager to reduce the load."
unknown_instructions = "Verify that the Pandora FMS agent is running"

Quelques éléments à prendre en compte:

• Tous les champs must doivent être définis. Si aucune donnée n'est disponible, laisser vide; notez le champ plugin_pass dans l'exemple ci-dessus.
• Utilisez des guillemets doubles dans les paires “…” pour définir des valeurs contenant des caractères spéciaux ou des espaces, comme le champ plugin_parameter dans l'exemple ci-dessus. Les fichiers INI contenant des caractères tels que ' “/ -_ ( ) [ ] et autres, must ont des guillemets doubles. Essayez d'éviter d'utiliser le caractère " pour les données. Si vous devez l'utiliser, escape avec la combinaison \".
• Si vous avez des doutes sur l'utilité ou la signification de ces champs, vérifiez tnetwork_component dans la base de données de Pandora FMS, car il contient pratiquement les mêmes champs. Lorsqu'un nouveau composant de réseau est créé, il est stocké dans cette base de données. Essayez de créer un composant réseau qui utilise votre plugin et analysez le registre d'entrée dans ce tableau pour comprendre toutes les valeurs.
• id_module: Il doit toujours être égal à 4 (ce qui signifie qu'il s'agit d'un module plugin).
• type: Définir le type de module: generic_data (1), generic_proc (2), generic_data_string (3) ou generic_data_inc (4) tel que défini dans ttipo_modulo.
• id_group: Il s'agit de la PK (primary key) de la table des groupes contenant les définitions des groupes. Le groupe 1 correspond à « tous les groupes » (All), et agit comme un groupe spécial.
• id_module_group: Il provient de la table tmodule_group. Il s'agit d'une association de modules par fonctionnalité, purement descriptive. Vous pouvez utiliser 1 pour le General module group.

Depuis Pandora FMS v5.1.SP1, les plugins du serveur utilisent des macros.

Le fichier plugin_definition.ini a également été modifié. Les champs suivants ont été ajoutés:

Dans la section plugin_definition:

• total_macros_provided qui définit le nombre de macros dynamiques que possède le plugin.

Dans la section module<N>:

• macro_<N>_value qui définit la valeur de ce module à l'aide de cette macro dynamique; si elle n'existe pas, c'est la valeur par défaut qui est retenue.

Et vous devez créer une section pour chaque macro dynamique, par exemple:

[macro_<N>]
hide = 0
description = <your_description>
help = <text_help>
value = <your_value>

Définition d'un plugin v2 (.pspz2) à des fins didactiques:

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

Retour à l'index de la documentation de Pandora FMS