個人用ツール

Pandora:Documentation ja:Anexo Server plugins developement

提供: Pandora FMS Wiki JP

移動先: 案内, 検索

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

サーバプラグイン開発

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

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

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

  • 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
  • Pandora サーバのインストール先の OS がサポートする任意のプログラミング言語を利用することができます。
  • All dependencies or necessary software to execute the plugin should be available or be installed in the same machine that executes the Pandora server.
  • プラグインの実行に必要な依存ソフトウエアは、Pandora サーバを実行するのと同一のマシンにインストールされている必要があります。

サーバプラグイン開発

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

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

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

以下のプラグインは、インタフェースの入出力トラフィックの合計を返します。データは 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.

この関数では、バージョンおよびプラグインの利用方法を説明しています。これはとても重要で、パラメータを指定せずにプラグインを実行するかまたは -h や --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:

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

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.

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

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

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

プラグインの手動登録



  • Name
  • 名前(Name)

Name of the plugin.

プラグインの名前です。

  • Plugin type
  • プラグインタイプ(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.

プラグインには、標準プラグインと Nagios の2種類があります。 標準プラグインは、アクションを実行してパラメータを受け取るスクリプトです。 Nagios プラグインは、その名前が示すように、Nagios で利用できる形式のプラグインです。主な違いは、テストが成功したかどうかを Nagios プラグインはエラーレベルで示すことです。

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.

もし Nagios プラグインを使いたい場合で(OK/NG ではなく)データを取得したい場合は、Nagios プラグインを "標準" モードで利用します。

  • Max. timeout
  • 最大タイムアウト(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.

プラグインの実行時間制限です。 この時間内に応答がない場合は、モジュールを不明として処理し、その値は更新されません。 プラグインを使用してモニタリングを実装する場合、これは非常に重要な要素です。そのため、プラグインの実行にかかる時間がこの数値より大きいと値を取得できません。この値は、プラグインとして使用されるスクリプトや実行ファイルが値を返すまでにかかる時間よりも常に大きくなければなりません。 何も設定しない場合は、plugin_timeout の設定値が使われます。

  • Plug-in command
  • プラグインコマンド(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, writte /usr/share/pandora_server/util/plugin/udp_nmap_plugin.shin the field.

プラグインコマンドのパスです。デフォルトインストールでのプラグインディレクトリは、/usr/share/pandora_server/util/plugin/ です。ただし、任意の場所を指定することができます。ここでは、フィールドに /usr/share/pandora_server/util/plugin/udp_nmap_plugin.sh を指定しています。

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

サーバは、このスクリプトを実行します。そのため、読み取りおよび実行権限がある必要があります。

  • Plug-in parameters
  • プラグインパラメータ(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_.

コマンドのパラメータ文字列で、コマンドの引数としてしていするものです。パラメータフィールドには、_field1_ _field2_ ... _fieldN_ といったマクロが使えます。

  • Parameters macros
  • パラメータマクロ(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.

プラグインパラメータフィールドで使うマクロを追加することができます。このマクロは、モジュール設定の通常のテキストフィールドとして表示されます。

PSPZ パッケージ

Pandora サーバプラグイン Zip ファイル (.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).

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

This section describe how to create a .pspz file.

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

パッケージファイル

A .pspz is a zip file with two files:

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

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.

[1] Here you have an example of .pspz file (renamed to .zip).

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

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

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

plugin_definition.ini の構造

ヘッダー/定義

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:

これがオプションセクションを持つ標準的な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: 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".

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

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

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

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

total_modules_provided: Defines how many modules are defined below. You should define at least one (for use as example as minimum).

total_modules_provided: 以下で定義するモジュールの数を指定します。(一例として使用するために)少なくとも1つはモジュールを定義してください 。

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

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

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

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.

これは動的セクション(セクション名に増加する数値を持つ)として定義され、必要な数だけ作成することができます。ここで定義したモジュール数と同じ値を、前のセクションのtotal_modules_providedに設定する必要があります。 もし4個のモジュールがある場合、セクション名はmodule1, module2, module3, 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 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.
  • どのフィールドも"忘れない"こと。すべてのフィールドが必須となっています。設定値がない場合は、上記例のplugin_passフィールドのように空白にしておくこと
  • 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.
  • 上記例のplugin_parameterフィールドのように、特殊文字や空白を含む値を定義する場合はダブルクォートで囲むこと。INIファイル中に ' " / - _ ( ) [ ] と言った文字を含む場合はダブルクォートを使用すること。データ中に " を含まないようにしましょう。もし必要になった場合は \" とエスケープしましょう
  • 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.
  • フィールドの意味や目的がよくわからない場合は、Pandora FMS データベースの tnetwork_component を参照してください。ほとんど同じフィールドがあります。ネットワークコンポーネントを作成する時は、利用するプラグインとデータベースに保存される全ての値を確認しながら作成してみてください。
  • id_module, should be 4 always (this means this is a plugin module).
  • id_moduleの値は常に4(これがプラグインモジュールであることを意味します)です。
  • 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.
  • typeはモジュールの種類を指定します。ttipo_moduloテーブルでgeneric_data (1), generic_proc (2), generic_data_string (3), generic_data_inc (4)が定義されています。
  • 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_groupはグループ定義を含むtgrupoテーブルのPK(プライマリキー)を設定します。1は"全グループ"を意味し、特別なグループのようにふるまいます。
  • 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.
  • id_module_groupの値はtmodule_groupテーブルを参照しており、モジュールの機能と関連づけられています。"1"を設定することで、一般モジュールグループを指定できます。

バージョン2

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

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



Template warning.png

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


Template warning.png

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


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

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

In section plugin_definition:

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

plugin_definitionセクション:

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

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.

module<N>セクション

  • macro_<N>_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.

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

Info.png

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


Info.png

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


Info.png

The previous version is still compatible. If the version parameter is not defined, then we assume that the version is version 1


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) のアップグレード

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:

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

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

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