Pandora:Documentation ja:Anexo Server plugins developement

From Pandora FMS Wiki

Jump to: navigation, search

Pandora FMS ドキュメント一覧に戻る

サーバプラグイン開発

サーバプラグインの基本機能

サーバプラグインは、Pandora FMS プラグインサーバにより実行されるため、次に示す特別な機能を備えている必要があります。

  • プラグインの実行では単一の値を返す必要があります。サーバプラグインは、プラグインモジュールによって実行されるためです。
  • リモートで監視対象のリソースにアクセスできる必要があります。
  • Pandora サーバのインストール先の OS がサポートする任意のプログラミング言語を利用することができます。
  • プラグインの実行に必要な依存ソフトウエアは、Pandora サーバを実行するのと同一のマシンにインストールされている必要があります。

サーバプラグイン開発

次に、Pandora FMS のサーバプラグインの例を説明します。

以下のプラグインは、インタフェースの入出力トラフィックの合計を返します。データは SNMP で取得します。

プラグインのコードは次の通りです。

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

このコードの重要な説明は、利用方法の関数にあります。

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

この関数では、バージョンおよびプラグインの利用方法を説明しています。これはとても重要で、パラメータを指定せずにプラグインを実行するかまたは -h や --help を指定してプラグインを実行した場合に常に表示される必要があります。

プラグインが返す値に関しては、最後から 2行目に標準出力に表示する以下のようなコマンドがあります。

print $inoctets+$outoctets;

見ての通り、プラグインが返す値は単一のデータで、これを Pandora プラグインサーバが関連モジュールにデータとして追加します。

このプラグインを実行するには、Pandora サーバを実行するマシンに snmpwalk および snmpget コマンドをインストールする必要があります。

PSPZ パッケージ

Pandora サーバプラグイン Zip ファイル (.pspz)

Pandora FMS 3.0では、プラグインおよび新しいプラグインを(プラグインに依存した、モジュールのライブラリのように)使用するモジュールを登録する新しい方法があります。基本的には、以下で説明する.pspzフォーマットのファイルをアップロードする管理コンソール拡張機能です。システムでファイルを読み込み、展開後、バイナリファイルとスクリプトをシステムにインストールし、Pandora FMSのモジュールライブラリへのプラグインの登録と.pspzファイル中で定義されたすべてのモジュール生成を行います。

この節では、.pspzファイルの作成方法について説明します。

パッケージファイル

.pspz ファイルは2つのファイルからなるzipファイルです。

plugin_definition.ini: プラグインとモジュールの仕様を含むファイル。ファイル名(大文字と小文字は区別されます)は固定です。

<script_file>: プラグインスクリプトもしくはバイナリファイルそのもの。ファイル名は自由につけることができます。

[1] ここに.pspzファイルのサンプル(ファイル名は.zipに変更されています)があります。

plugin_definition.ini の構造

ヘッダー/定義

これがオプションセクションを持つ標準的なINIファイルです。 最初のセクションは最も重要で、セクション名は"plugin_definition"固定です。 以下に例を示します。

[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: 先に<script_file>で参照されていた、.pspzファイルに含まれるスクリプト名と同じ値となります。このサンプルでは"ssh_pandoraplugin.sh"というシェルスクリプトです。

*_opt: プラグインに登録するオプションを指定します。Pandora FMSコンソールで"手動で"プラグインを登録するフォームに表示されるものと同様のものです。

plugin_type: 標準的なPandora FMSプラグインの場合は0、Nagiosタイププラグインの場合は1を指定します。

total_modules_provided: 以下で定義するモジュールの数を指定します。必要最小限の値を指定してください(XXX)

execution_command: 値が設定された場合、スクリプトの前に値が追加されます。"java -jar"といったインタプリタを指定する際に設定されます。したがって、プラグインはPandora FMSプラグインサーバから"java -jar <plugin_path>/<plugin_filename>"と実行されます。

execution_postcommand: 値が設定された場合、追加パラメータがplugin_filenameの後にプラグインに渡されます。追加パラメータはユーザには見えません。

モジュール定義 / ネットワークコンポーネント

これは動的セクション(セクション名に増加する数値を持つ)として定義され、必要な数だけ作成することができます。ここで定義したモジュール数と同じ値を、前のセクションのtotal_modules_providedに設定する必要があります。 もし4個のモジュールがある場合、セクション名はmodule1, module2, module3, module4となります。

以下にモジュール定義の例を示します。

[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"

注意すべき点がいくつかあります。

  • どのフィールドも"忘れない"こと。すべてのフィールドが必須となっています。設定値がない場合は、上記例のplugin_passフィールドのように空白にしておくこと
  • 上記例のplugin_parameterフィールドのように、特殊文字や空白を含む値を定義する場合はダブルクォートで囲むこと。INIファイル中に ' " / - _ ( ) [ ] と言った文字を含む場合はダブルクォートを使用すること。データ中に " を含まないようにしましょう。もし必要になった場合は \" とエスケープしましょう
  • フィールドの意味や目的がよくわからない場合は、Pandora FMS データベースの tnetwork_component を参照してください。ほとんど同じフィールドがあります。ネットワークコンポーネントを作成する時は、利用するプラグインとデータベースに保存される全ての値を確認しながら作成してみてください。
  • id_moduleの値は常に4(これがプラグインモジュールであることを意味します)です。
  • typeはモジュールの種類を指定します。ttipo_moduloテーブルでgeneric_data (1), generic_proc (2), generic_data_string (3), generic_data_inc (4)が定義されています。
  • id_groupはグループ定義を含むtgrupoテーブルのPK(プライマリキー)を設定します。1は"全グループ"を意味し、特別なグループのようにふるまいます。
  • id_module_groupの値はtmodule_groupテーブルを参照しており、XXXX。"1"を設定することで、一般モジュールグループを指定できます。

バージョン2

Pandora FMS v5.1 SP1 から、サーバプラグインはマクロを利用します。



Template warning.png

これらのプラグインは、.pspz2 という拡張子で区別されます。

 


また、plugin_definition.ini が変更になっています。次のフィールドが追加されました。

plugin_definitionセクション:

  • total_macros_provided プラグインが持つ動的マクロの数を定義します。

module<N>セクション

  • macro_<N>_value 動的マクロを使ったモジュールの値を定義します。存在しない場合はデフォルト値が利用されます。

そして、それぞれの動的マクロ用の次のような新たなセクションが作られています。

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

この新たな構造をバージョン2 とします。

Info.png

execution_postcommand の部分に指定したマクロの置換 (_fieldx_) を明示的に呼び出す必要があります。以下の例を参照してください。

 


Info.png

以前のバージョンとの互換性もあります。バージョンパラメータが定義されてなければ、バージョン1 と想定します。

 


バージョン2 のプラグイン定義例

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

古い PSPZ (Pandora バージョン 4) のアップグレード

サーバプラグインの動的パラメータが無い、パラメータが静的な以前の PSPZ は、新しいバージョンの pandora では動作しません。これを修正する手順は以下にあります。

以前のバージョンからのアップグレード → メジャーバージョンのアップデート → バージョン 4.x から 5.0 へのアップデート → プラグイン