目次

サーバプラグイン開発

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

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

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

サーバプラグインは、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 コマンドをインストールする必要があります。

プラグインの手動登録

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

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

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 の設定値が使われます。

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.

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

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_ といったマクロが使えます。

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 サーバでチェックできます。

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

これらの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_

When this plugin is used in a Module, the DNS Plugin will be executed replacing each of the fields with the parameters that are written in the Module.

このプラグインをモジュールで利用する際には、それぞれのフィールドはモジュールのパラメータに置き換えられ DNS Plugin が実行されます。 

/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_ を追加します。


If any module or component is using that server plugin, a lock icon that cannot be updated will appear.


モジュールまたはコンポーネントがそのサーバプラグインを使用している場合、更新できないロックアイコンが表示されます。

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 ドメインがあり、名前によってさまざまなコンポーネント(ダッシュボード、レポートなど)で簡単に識別できることです。

マクロ一覧

PSPZ パッケージ

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

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

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

パッケージファイル

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

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

<script_file>: プラグインスクリプトもしくはバイナリファイルそのもの。ファイル名は自由につけることができます。ここ に、.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: 先に<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の後にプラグインに渡されます。追加パラメータはユーザには見えません。

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


Define the same number of modules as those defined in total_modules_provided from the previous section.


前のセクションの total_modules_provided で定義したものと同じ数のモジュールを定義します。

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"

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

バージョン2

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

These plugins will be differentiated by the extension of the pspz2 file. If it does not have this extension, a type 1 PSPZ (without dynamic macros in the remote plugin extension) will be assumed.

これらのプラグインは、.pspz2 という拡張子で区別されます。この拡張子がない場合は、タイプ 1 PSPZ (リモートプラグイン拡張に動的マクロがない) とみなされます。

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

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

In the section plugin_definition:

plugin_definition セクション:

In the section module<N>:

module<N> セクション

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>
  • Macros must be called in the execution_postcommand section to perform the substitution (see example).
  • The previous version is still supported. If the version parameter is not defined, the version is assumed to be 1.
  • execution_postcommand の部分に指定したマクロの置換 (_fieldx_) を明示的に呼び出す必要があります。(以下の例を参照してください。)
  • 以前のバージョンとの互換性もあります。バージョンパラメータが定義されてなければ、バージョン1 と想定します。

例

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 ドキュメント一覧に戻る

(OBSOLETE) 古い PSPZ のアップグレード

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.

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