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

The server plugin is executed by the Pandora FMS Plugin Server, so it must have some special features:

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

• Each execution of the plugin must return a single value. This must be the case since the Plugin Server performs one execution for each Plugin Module.
• You must be able to access the resources to be monitored remotely.
• It is possible to use any programming language supported by the operating system where the Pandora FMS server is installed.
• All the dependencies or software needed to run the plugin should be available or installed in the same machine that runs the Pandora FMS server.

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

More information about monitoring with remote server plugins can be found at this link. There you will get simpler examples and how they work with the Modules and the Agents that contain them. This article discusses in detail the creation of server plugins.

リモートサーバプラグインを使った監視に関する詳細は、こちらを確認してください。そこには、簡単な例と、モジュールとエージェントがどのように機能するかが記載されています。 この記事では、サーバプラグインの作成について詳しく示します。

次に、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 コマンドをインストールする必要があります。

• プラグインタイプ(Plugin type)

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

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

• 最大タイムアウト(Max. timeout)

This is the expiration time of the add-on. If no response is received within this time, the Module will be marked as unknown and its value will not be updated. This is a very important factor when implementing monitoring with plugins, because if the time it takes to execute the plugin is greater than this number, you will never be able to obtain values with it. This value must always be greater than the time it normally takes for the script or executable used as a plugin to return a value. If nothing is specified, the value specified in the configuration as plugin_timeout will be used.

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

• プラグインコマンド(Plug-in command)

It is the path where the plugin command is. By default, if the installation has been standard, they will be in the directory /usr/share/pandora_server/util/plugin/, although it can be any path of the system. For this case, write /usr/share/pandora_server/util/plugin/udp_nmap_plugin.sh in 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 it must have access and execution permissions on it.

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

• プラグインパラメータ(Plug-in parameters)

A string with the plugin parameters, which will follow the command and a blank space. This field accepts macros such as _field1_ _field2_ … _fieldN_. The following section expands on how macros work.

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

• パラメータマクロ(Parameters macros)

It is possible to add unlimited macros for use in the plugin parameters field. These macros will appear as text fields in the Module configuration. The following section expands on how macros work.

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

Conside the DNS Plugin installed by default in Pandora FMS server.

Pandora FMS サーバにデフォルトでインストールされている DNSプラグイン について考えてみます。

Said plugin, among other uses, allows for a web domain and its corresponding IP to be checked by a DNS server.

このプラグインを使用すると、Webドメインとそれに対応する IP を DNS サーバでチェックできます。

• -i : Known domain IP address.
• -d : Corresponding web domain.
• -s : DNS server for checking. Knowing these three parameters, proceed to manually register a new plugin, add the name“New DNS Plugin” and in the description copy the previous summary and in addition indicate that it is necessary for the Module to retrive a false value (0) or true (1) for monitoring. This type of data is also known as boolean and in Pandora FMS it is called generic_proc .

In the section Macro parameters add three macro fields field1, field2 and field3.

• -i : 既知のドメインの IP アドレス。
• -d : 対応する Web ドメイン。
• -s : チェックする DNS サーバ。

これらの3つのパラメータで、新しいプラグインの手動登録に進み、“New DNS Plugin” という名前で、説明に前の概要をコピーします。さらに 監視のためにモジュールが false(0) または true(1) を取得する必要があることを示します。 このタイプのデータはブール値とも呼ばれ、Pandora FMS では generic_proc と呼ばれます。 セクション マクロパラメータ(Macro parameters) に、3つのマクロフィールド field1, field2 および field3 を追加します。

For _field1_ add the description according to the -i parameter and so on for parameters -d and -s . Leave the values by default empty, type in in the Help of each one of them the text you wish.

_field1_ では、パラメーター -i に関する説明を追加します。同様に、-d および -s の説明を追加します。 デフォルト(default) の値を空のままにし、それぞれの ヘルプ(Help) に必要なテキストを入力します。

In the text box Plugin command type in:

テキストボックスに プラグインコマンド を入力します。

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

In the Plugin parameters text box, type in:

プラグインパラメータ(Plugin parameters) ボックスに入力します。

-i _field1_ -d _field2_ -s _field3_

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

Macros work like _field1_, _field2_, (…), _fieldN_, but they host special values both from the Modules and the Agents those Modules contain.

マクロは _field1_, _field2_, (…), _fieldN_ のように機能しますが、モジュールとそれらのモジュールを含むエージェント両方からの特別な値を利用します。

Going back to the example of the previous section where the default values of the _fieldN_ were left blank. Edit it for the default value of _field2_ and add the macro _module_.

_fieldN_ のデフォルト値が空白のままになっている前の章の例に戻ります。_field2_ のデフォルト値を編集し、マクロ _module_ を追加します。

The _module_ macro returns the Module the plugin uses and will be added to the user or policy when said Module is created. To verify this, create a new Agent called “DNS verify” and a new Module through the option Create a new plugin server module:

_module_ マクロは、プラグインが使用するモジュールを返し、そのモジュールが作成されるときにユーザまたはポリシーに追加されます。 これを確認するには、“DNS verify” と呼ばれる新しいエージェントを作成し、 プラグインサーバモジュールの新規作成(Create a new plugin server module) オプションを使用して新しいモジュールを作成します。

Once you are again in the new Module editing form, in Plugin select the “New DNS Plugin” list and the _module_ macro will appear like this:

新しいモジュールの編集フォームで、プラグインで “New DNS Plugin” をリストから選択すると、_module_ マクロが次のように表示されます。

Rememeber to add that the type of data to be collected must be “Generic boolean” and for the name of the new Module, just add the web domain whose IP address you are going to verify with a specified DNS server. Save it and check it works.

収集するデータのタイプは “Generic boolean” である必要があることを忘れないでください。また、 新しいモジュールの名前、指定した DNS サーバで IP アドレスを確認する Web ドメインを追加します。 保存して機能することを確認します。

The advantage of this method is that it will have both Modules and Web domains you need to check and they are easily identified in different components (Dashboards, reports, etc.) through its name.

この方法の良い点は、モジュールとしてチェックする必要のある Web ドメインがあり、名前によってさまざまなコンポーネント(ダッシュボード、レポートなど)で簡単に識別できることです。

• _agent_ : Agent alias to be used in the macro. If no alias is assigned, the name of the agent will be used.
• _agentalias_ : Agent alias to be used in the macro.
• _agentdescription_ : Description of the agent to be used in the macro.
• _agentstatus_ : Current status of the Agent when used in the macro.
• _agentgroup_ : Name of the Agent group to be used in the macro.
• _agentname_ : Name of the Agent to be used in the macro (see also _agente_ > ).
• _address_ : Agent adress to be used in the macro.
• _module_ : Name of the Module to be used in the macro.
• _modulegroup_ : Name of the Module group to be used in the macro.
• _moduledescription_ : Description of the module to be used in the macro.
• _modulestatus_ : Status of the module to be used in the macro.
• _moduletags_ : URL associated to the module tags.
• _id_module_ : ID of the module to be used in the macro.
• _id_agente_ : ID of the agent to be used in the macro, useful for building the URL of access to Pandora FMS console.
• _id_group : ID of the agent group to be used for the macro.
• _interval_ : Interval of the modules execution to be used for the macro.
• _target_ip_ : Target IP address of the module to be used for the macro.
• _target_port_ : Target port of the module to be used for the macro.
• _policy_ : Name of the policy the module belongs to (if it applies).
• _plugin_parameters_ : Plugin parameters of the module to be used in the macro.
• _email_tag_ : Email inboxes associated to the module tags.
• _phone_tag_ : Phone numbers associated to the module tags.
• _name_tag_ : Name of the tags associated to the module for the macro.

• _agent_ : エージェントの別名。別名が割り当てられていない場合は、エージェント名が使用されます。
• _agentalias_ : エージェントの別名。
• _agentdescription_ : エージェントの説明。
• _agentstatus_ : エージェントの現在の状態。
• _agentgroup_ : エージェントグループ名。
• _agentname_ : エージェント名。(_agent_ も参照してください)
• _address_ : エージェントのアドレス。
• _module_ : モジュール名。
• _modulegroup_ : モジュールグループ名。
• _moduledescription_ : モジュールの説明。
• _modulestatus_ : モジュールの状態。
• _moduletags_ : モジュールタグに関連付けられた URL。
• _id_module_ : モジュールの ID。
• _id_agente_ : エージェントの ID。Pandora FMS コンソールへアクセスする URL を生成するのに便利です。
• _id_group : エージェントグループの ID。
• _interval_ : モジュールの実行間隔。
• _target_ip_ : モジュールのターゲット IP。
• _target_port_ : モジュールのターゲットポート番号。
• _policy_ : モジュールが所属するポリシー名。(適用される場合)
• _plugin_parameters_ : モジュールのプラグインパラメータ。
• _email_tag_ : モジュールタグに関連付けられた Email。
• _phone_tag_ : モジュールタグに関連付けられた電話番号。
• _name_tag_ : モジュールに関連付けられたタグ名。

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

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

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

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

<script_file>: プラグインスクリプトもしくはバイナリファイルそのもの。ファイル名は自由につけることができます。ここ に、.pspzファイルのサンプル(ファイル名は.zipに変更されています)があります。

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: 先に<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の後にプラグインに渡されます。追加パラメータはユーザには見えません。

If you have for example four modules, the names of those sections must be: module1, module2, module3 and module4.

もし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 head of department"
warning_instructions = "Calling the server manager to reduce the load"
unknown_instructions = "Verify that Pandora FMS agent is running"

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

• どのフィールドも”忘れない”こと。すべてのフィールドが必須となっています。設定値がない場合は、上記例のplugin_passフィールドのように空白にしておくこと
• 上記例のplugin_parameterフィールドのように、特殊文字や空白を含む値を定義する場合はダブルクォートで囲むこと。INIファイル中に ' “ / - _ ( ) documentation_ja と言った文字を含む場合はダブルクォートを使用すること。データ中に ” を含まないようにしましょう。もし必要になった場合は \“ とエスケープしましょう
• フィールドの意味や目的がよくわからない場合は、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“を設定することで、一般モジュールグループを指定できます。

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

Also plugin_definition.ini has changed. The following fields have been added:

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

In the section plugin_definition:

plugin_definition セクション:

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

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

In the section module<N>:

module<N> セクション

• macro_<N>_value that defines the value for that Module using that dynamic macro, if it does not exist the default value is taken.

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

And you must create a section for each dynamic macro, for example:

また、動的マクロごとにセクションを作成する必要があります。次に例を示します。

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

Definition of a v2 plugin (.pspz2) for didactic purposes:

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

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

From Pandora FMS version 4, some PSPZ prior to parameter dynamic field creation for plugins and had fixed parameters, will not work in new versions.

Pandora FMS バージョン 4 までのサーバプラグインの動的パラメータが無い、パラメータが静的な以前の PSPZ は、 新しいバージョンの pandora では動作しません。

To migrate them, execute them with the appropriate credentials and after carrying out the upgrading process, the following:

それらを移行するには、適切な権限でアップグレードプロセスを実行した後、次の手順を実行します。

/usr/share/pandora_server/util/pandora_migrate_plugins.pl <dbname> <dbhost> <dbuser> <dbpass>

Find more information about major and minor version update in this link.

メジャーおよびマイナーバージョンのアップデートに関する詳細は、こちらを参照してください。