個人用ツール

Pandora:Documentation ja:Anexo Console extensions development

提供: Pandora FMS Wiki JP

移動先: 案内, 検索

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

コンソールの拡張

Extensions are a form to develop new functionality for your Pandora Console as plugins.

拡張は、プラグインとして新たな機能を Pandora コンソールに開発するためのものです。

In this article you will learn how to develop a extension:

この章では、拡張の開発の仕方を説明します。

「拡張」の種類

There are two Kinds of Extensions:

拡張には 2つの種類があります。

  • Visibles, extensions that are shown in Pandora Menu.
  • 表示される拡張は、Pandora のメニューに表示されます。
  • Invisibles, extensions that are loaded and executed in index.php of Pandora Menu but doesn't apeare in Pandora Menu.
  • 非表示の拡張は、Pandora メニューである index.php からロードされ実行されますが、Pandora メニューには表示されません。

「拡張」のディレクトリ

The directory of extensions is a subdirectory in your local installation of Pandora Console with the name "extensions". This directory contains for each extension the following:

Main file of the extension
This file has the code to load in Pandora Console
Subdirectory of extension
this is optional and may contain the Icon image file (a 18x18 image) to show next to the name of the extension in the menu and others files as translations, modules, images...

拡張のディレクトリは、Pandora コンソールをインストールしたディレクトリ内の "extensions" というサブディレクトリです。このディレクトリは、次のようは拡張が含まれています。

拡張のメインファイル
Pandora コンソールにロードされるコードです。
拡張のサブディレクトリ
これはオプションで、メニュー内の拡張名の隣に表示されるアイコンの画像ファイル (18x18 のサイズ) および、その他、翻訳、モジュール、画像ファイルなどが含まれます。

「拡張」のテンプレート

<?php

< Comments with license, author/s, etc... >

< php auxiliary code as functions, variables, classes that your extension use >

function < name of main function > () {
	< Main function Code >
}

/*-------------------------------------*/

/* Adds the link in the operation menu */
add_operation_menu_option ('< Name Extension >', '< father ID menu >', '< relative path Icon >');

/* Adds the link in the godmode menu */
add_godmode_menu_option ('< Name Extension >', '< ACL level >', '< father ID menu >', '< relative path Icon >')

/*-------------------------------------*/

/* Sets the callback function to be called when the extension is selected in the operation menu */
add_extension_main_function ('< name of main function >');

/* Sets the callback function to be called when the extension is selected in the godmode menu */
add_extension_godmode_function ('< name of godmode function >');
?>

「拡張」の API

The API for extensions is stil under development and may change in the future.

拡張の API はまだ開発途上で、将来変更するかもしれません。

You can get more information about the API in the pandora-develop mailng list.

API に関する詳細情報は、pandora-develop メーリングリスト も参照してください。

The following sections contain the description of the functions in the API for extensions:

以下の章では、拡張に関する API の関数の説明をします。

extensions_add_operation_menu_option

extensions_add_operation_menu_option ('< string name >', '< father ID menu >', '< relative path Icon >'): this function adds the link to the extension with the given name in the Operations menu. The third parameter is optional and is the relative path to the icon image ( 18x18 pixels) to apear next to the link, if this parameter is not defined an icon of a plug (Extensions.png) will be used.

extensions_add_operation_menu_option ('< 拡張名 >', '< メニューの親ID >', '< アイコンの相対パス >'): この関数は、拡張へのリンクを指定した名称で 操作(Operations) メニューに追加します。3番目のパラメータはオプションで、アイコン画像 (18x18 ピクセル) への相対パスを指定します。パラメータを設定しない場合は、コンセントのアイコン (Extensions.png) が利用されます。

extensions_add_godmode_menu_option

extensions_add_godmode_menu_option ('< Name Extension >', '< ACL level >' , '< father ID menu >', '< relative path Icon >'): this function adds the link to the extension with the given name in the Godmode menu if the user has the required ACL level as indicated by the second parameter. The forth parameter is optional and is the relative path to the icon image ( 18x18 pixels) to apear next to the link, if this parameter is not defined an icon of a plug (Extensions.png) will be used.

extensions_add_godmode_menu_option ('< 拡張名 >', '< ACL レベル >', '< メニューの親ID >', '< アイコンの相対パス >'): この関数は、ユーザが 2番目のパラメータで指定された ACL レベルを満たす場合に、拡張へのリンクを指定した名称で システム管理(Godmode) メニューに追加します。4番目のパラメータはオプションで、アイコン画像 (18x18 ピクセル) への相対パスを指定します。パラメータを設定しない場合は、コンセントのアイコン (Extensions.png) が利用されます。

extensions_add_main_function

extentions_add_main_function ('< name of main function >'): sets the callback function that will be called when the user clicks on the link to the extension in the operation menu

extensions_add_main_function ('< メイン関数名 >'): 操作(operation)メニューで拡張のリンクをクリックしたときに呼び出される関数を設定します。

extensions_add_godmode_function

extensions_add_godmode_function ('< name of godmode function >'): add the function of extension for to call one time when the user go to extension in Pandora Console godmode instead load main_function.

extensions_add_godmode_function ('< システム管理メニュー関数名 >'): Pandora コンソールのシステム管理メニューの拡張のリンクをクリックしたときに呼び出される関数を設定します。

extensions_add_login_function

extensions_add_login_function ('< name of login function >'): add the function of extension for to call one time when the user login correctly in Pandora console.

extensions_add_login_function ('< ログイン関数名 >'): Pandora コンソールへユーザが正しくログインしたときに呼び出される関数を設定します。

extensions_add_godmode_tab_agent

extensions_add_godmode_tab_agent('< ID of extension tab >', '< Name of extension tab >', '< Image file with relative dir >', '< Name of function to show content of godmode tab agent >'): adds one more tab to the agent edit view that when it is selected executes the code of the name function that we pass to it.

extensions_add_godmode_tab_agent('< 拡張タブ ID >', '< 拡張タブ名 >', '< 画像ファイルの相対パス >', '< エージェント管理のタブから実行される関数名 >'): エージェント編集画面に 1つ以上のタブを追加します。それが選択された場合は、指定した名前の関数が呼び出されます。

extensions_add_opemode_tab_agent

extensions_add_opemode_tab_agent('< ID of extension tab >', '< Name of extension tab >', '< Image file with relative dir >', '< Name of function to show content of operation tab agent >'):adds one more tab to the agent operating view than when it is selected will execute the code of the name function that we pass to it.

extensions_add_opemode_tab_agent('< 拡張タブ ID >', '< 拡張タブ名 >', '< 画像ファイルの相対パス >', '< エージェント参照のタブから実行される関数名 >'): エージェント参照画面に 1つ以上のタブを追加します。それが選択された場合は、指定した名前の関数が呼び出されます。

extensions_add_translation_string_function (>= 7.0)

extensions_add_translation_string_function('< Name of translation function >'):sets the callback function that will be called from common translation function for extensions, ___().

extensions_add_translation_string_function('< 翻訳関数名 >'): 拡張共通の翻訳関数 ___() から呼び出される関数を設定します。

メニューの親 ID

List of available strings IDs for use in extension API. If use null value or not incluyed param in call function, the extension appear only in submenu of extension.

拡張 API で利用できる ID 文字列を示します。呼び出し関数で指定しなかったり、以下に無いものを指定した場合は、拡張のサブメニューにのみ表示されます。

操作

  • 'estado': View agents
  • 'estado': エージェント参照(View agents)
  • 'visualc': Visual console
  • 'visualc': ビジュアルコンソール(Visual console)
  • 'estado_server': Pandora servers
  • 'estado_server': Pandora サーバ(Pandora servers)
  • 'incidencias': Manage incidents
  • 'incidencias': インシデント管理(Manage incidents)
  • 'eventos': View events
  • 'eventos': イベント参照(View events)
  • 'usuarios' View users
  • 'usuarios' ユーザ参照(View users)
  • 'snmpconsole': SNMP console
  • 'snmpconsole': SNMP コンソール(SNMP console)
  • 'messages': Messages
  • 'messages': メッセージ(Messages)
  • 'reporting': Reporting
  • 'reporting': レポート(Reporting)

システム管理

  • 'gagente': Manage agents
  • 'gagente': エージェント管理(Manage agents)
  • 'gmodules': Manage modules
  • 'gmodules': モジュール管理(Manage modules)
  • 'galertas': Manage alerts
  • 'galertas': アラート管理(Manage alerts)
  • 'gusuarios': Manage users
  • 'gusuarios': ユーザ管理(Manage users)
  • 'gsnmpconsole': Manage SNMP console
  • 'gsnmpconsole': SNMP コンソール管理(Manage SNMP console)
  • 'greporting': Manage reports
  • 'greporting': レポート管理(Manage reports)
  • 'gperfiles': Manage profiles
  • 'gperfiles': プロファイル管理(Manage profiles)
  • 'gservers': Manage servers
  • 'gservers': サーバ管理(Manage servers)
  • 'glog': System audit log
  • 'glog': システム監査ログ(System audit log)
  • 'gsetup': Setup
  • 'gsetup': 設定(Setup)
  • 'gdbman': DB maintenance
  • 'gdbman': DBメンテナンス(DB maintenance)
エンタープライズ版の管理

Info.png

These elements are only available with Enterprise version


Info.png

これらの要素は、Enterprise版にのみあります。


  • gpolicies: Manage policies
  • gpolicies: ポリシー管理

The extension screenshot when is running.

The extension show a table where the colummns are Modules groups and the rows the Agent groups. And each cell have a colour with the next meanings:

  • Green: when all modules of Group are OK.
  • Yellow: when at least one monitor in warning.
  • Red: At least one monitor fails.

列がモジュールのグループ、行がエージェントグループの表を表示する拡張です。また、それぞれのセルは、次のような意味の色が表示されます。

  • : すべてのモジュールが正常
  • 黄色: 少なくとも一つのモニタ項目が警告状態
  • : 少なくとも一つのモニタ項目が障害状態

And this extension hang from the Operation menu in Agents.

そして、この拡張は、操作メニューのエージェント参照から呼び出されます。

 

ソースコード

<?php
/**
 * Pandora FMS- http://pandorafms.com
 * ==================================================
 * Copyright (c) 2005-2009 Artica Soluciones Tecnologicas
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation for version 2.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 */
 
/**
 * Extension specific translation function
 */
 function extensions_translation() {
   $translates = array(
     'es' => array(
       "sentence" => "translated sentence"
     ),
     /*
      ... for other language's definitions.
     */
   );

   $args = func_get_args();
   $string = array_shift($args);
   $user_language = get_user_language ();
   if(isset($translates[$user_language][$string])){
     return vsprintf($translates[$user_language][$string], $args);
   }
   else{
     return false;
   }
 }

/**
 * Translate the array texts using gettext
 */
 function translate(&$item, $key) {
 	$item = ___($item);
 }
 
/**
 * The main function of module groups and the enter point to
 * execute the code.
 */
function mainModuleGroups() {
	global $config; //the useful global var of Pandora Console, it has many data can you use
	
	//The big query
	$sql = "select COUNT(id_agente) AS count, estado
		FROM tagente_estado
		WHERE utimestamp != 0 AND id_agente IN
			(SELECT id_agente FROM tagente WHERE id_grupo = %d AND disabled IS FALSE)
			AND id_agente_modulo IN
			(SELECT id_agente_modulo 
				FROM tagente_modulo 
				WHERE id_module_group = %d AND disabled IS FALSE AND delete_pending IS FALSE)
		GROUP BY estado";
	
	echo "<h1>" . ___("Combine table of agent group and module group") . "</h1>";
	
	echo "<p>" . ___("This table show in columns the modules group and for rows agents group. The cell show all modules") . "</p>";
	
	
	$agentGroups = get_user_groups ($config['id_user']);
	$modelGroups = get_all_model_groups();
	array_walk($modelGroups, 'translate'); //Translate all head titles to language is set
	
	$head = $modelGroups;
	array_unshift($head, ' ');
	
	//Metaobject use in print_table
	$table = null;
	$table->align[0] = 'right'; //Align to right the first column.
	$table->style[0] = 'color: #ffffff; background-color: #778866; font-weight: bolder;';
	$table->head = $head;
	
	//The content of table
	$tableData = array();
	//Create rows and celds
	foreach ($agentGroups as $idAgentGroup => $name) {
		
		$row = array();
		
		array_push($row, $name);
		
		foreach ($modelGroups as $idModelGroup => $modelGroup) {
			$query = sprintf($sql,$idAgentGroup, $idModelGroup);
			$rowsDB = get_db_all_rows_sql ($query);
			
			$states = array();
			if ($rowsDB !== false) {
				foreach ($rowsDB as $rowDB) {
					$states[$rowDB['estado']] = $rowDB['count'];	
				}
			}
			
			$count = 0;
			foreach ($states as $idState => $state) {
				$count = $state;
			}
			
			$color = 'transparent'; //Defaut color for cell
			if ($count == 0) {
				$color = '#babdb6'; //Grey when the cell for this model group and agent group hasn't modules.
				$alinkStart = '';
				$alinkEnd = '';
			}
			else {
				$alinkStart = '<a href="index.php?sec=estado&sec2=operation/agentes/status_monitor&status=-1&ag_group=' . $idAgentGroup . 
					'&modulegroup=' . $idModelGroup . '">';
				$alinkEnd = '</a>';
				
				if (array_key_exists(0,$states) && (count($states) == 1))
					$color = '#8ae234'; //Green when the cell for this model group and agent has OK state all modules.
				else {
					if (array_key_exists(1,$states))
						$color = '#cc0000'; //Red when the cell for this model group and agent has at least one module in critical state and the rest in any state.
					else
						$color = '#fce94f'; //Yellow when the cell for this model group and agent has at least one in warning state and the rest in green state.
				}
			}
			
			array_push($row,
				'<div
					style="background: ' . $color . ' ;
						height: 15px;
						margin-left: auto; margin-right: auto;
						text-align: center; padding-top: 5px;">
					' . $alinkStart . $count . ' modules' . $alinkEnd . '</div>');
		}
		array_push($tableData,$row);
	}
	$table->data = $tableData;
	
	print_table($table);
	
	echo "<p>" . ___("The colours meaning:") .
		"<ul>" .
		'<li style="clear: both;">
			<div style="float: left; background: #babdb6; height: 20px; width: 80px;margin-right: 5px; margin-bottom: 5px;"> </div>' .
			___("Grey when the cell for this model group and agent group hasn't modules.") . "</li>" .
		'<li style="clear: both;">
			<div style="float: left; background: #8ae234; height: 20px; width: 80px;margin-right: 5px; margin-bottom: 5px;"> </div>' . 
			___("Green when the cell for this model group and agent has OK state all modules.") . "</li>" .
		'<li style="clear: both;"><div style="float: left; background: #cc0000; height: 20px; width: 80px;margin-right: 5px; margin-bottom: 5px;"> </div>' . 
			___("Red when the cell for this model group and agent has at least one module in critical state and the rest in any state.") . "</li>" .
		'<li style="clear: both;"><div style="float: left; background: #fce94f; height: 20px; width: 80px;margin-right: 5px; margin-bottom: 5px;"> </div>' . 
			___("Yellow when the cell for this model group and agent has at least one in warning state and the rest in green state.") . "</li>" .
		"</ul>" .
		"</p>";
}
 
extensions_add_operation_menu_option("Modules groups", 'estado', 'module_groups/icon_menu.png');
extensions_add_main_function('mainModuleGroups');
extensions_add_translation_string_function('extensions_translation');
?>

説明

In the source code there are two parts:

ソースコードは、2つのパーツにわかれています。

  • The source code of extension.
  • 拡張のソースコード
  • The API calls functions.
  • API を呼び出す関数

The order of parts is indifferent, but it's better put "The API calls functions" in the bottom of you main file extension because the style guidelines advise to add this part into bottom thus all extensions have more or less a same style.

パーツの順番は関係ありませんが、APIを呼び出す関数は拡張ファイルの下の方が良いです。なぜなら、スタイルのガイドラインでは、この部分を下に書くようにアドバイスしているためです。それにより、すべての拡張は同じようなスタイルになります。

拡張のソースコード

In this case for this example has two function in the same file, but if you has a complex code, it is better divide in many files (and it save in subdirectory extension), the functions are:

この例の場合、同じファイルに 3つの関数があります。しかし、共通のコードがあるのであれば、複数ファイルに分割する方が良いです(そして、拡張のサブディレクトリに保存します)。関数は次の通りです。

  • function extensions_translation() (>= 7.0)
  • extensions_translation() 関数 (>= 7.0)
This function is for extension specific translation. It is called from the common translation function, ___() (three of '_'. not __()).
拡張独自の翻訳に使用されます。共通の翻訳関数である ___() ('_' が 3つで、__() ではありません) から呼び出されます。
  • function translate(&$item, $key)
  • translate(&$item, $key) 関数
This function use for callback in the array_walk function. Because the main function keep the titles of columns and the titles of rows in array without translations.
この関数は、array_walk 関数内のコールバックに使われます。なぜなら、メイン関数は、配列の行と列のタイトルを変換せずに維持するためです。
  • function mainModuleGroups()
  • mainModuleGroups() 関数
This is the heard of extension, and it's huge of lines, I see not all code, see some important parts:
これは、拡張のコードで何行もあります。重要な部分のみ示します。
  • The first is access to config global var. In this var has many configurations and default values for many things of Pandora Console.
  • 最初は、設定のグローバル変数へのアクセスです。この変数に、Pandora コンソールに関する多くの設定やデフォルト値が含まれます。
  • The second var is the query in MySQL into a string. And the %d is the format placeholders is for Id Group and Id Module Group and these are sustitute for value in sprintf function into foreach loops.
  • 2つ目の変数は、MySQLのクエリを文字列で設定しています。ここで、%d は、グループID および モジュールグループID を示す、書式化文字列です。これらの変数は、foreach ループの中の sprintf 関数 で使われます。
  • Some echos for print the text before the table.
  • 次に表示するためのいくつかの echo があります。
  • Extract of DB two arrays with one dimension and the index is id, and the content is title for columns (Module groups) and rows (Agent group) in each case.
  • DB のデータを 1次元の 2つの配列に展開し、id がインデックスで、内容は列(モジュールグループと行(エージェントグループ)にタイトルです。
  • Translate the Model Group array titles.
  • モジュールグループ配列のタイトルを変換します。
  • Make the meta-object $table, fill by rows and print.
  • メタオブジェクトの $table を作成し、行を埋めて表示します。
  • Before the foreach loops, define into $table the head and styles of table.
  • foreach ループの前に、$table に、テーブルのヘッダとスタイルを定義します。
  • The first loop is for rows (each agent group).
  • 最初のループは行のデータ用です。(それぞれのエージェントグループ)
  • The second loop is for columns in current row (each model group).
  • 2つ目のループは、現在の行に対する列のデータ用です。(それぞれのモジュールグループ)
  • Then for each cell, it has two number, id model group and id agent group, with this two number we make a query to database and we obtain the files.
  • そして、それぞれのセルに、モジュールグループとエージェントグループの ID の 2つの数字が当てはまり、この 2つの数字を使ってデータベースクエリを実施し、データを取得します。
  • Proccess the result array for obtain other array that is array and the index is a integer of diferents kinds of monitor states and the content is a count of monitor in this state.
  • 異なる種類のモニタ状態および、状態の数の合計の結果の配列を生成します。
  • Well, the only thing left is to make or fill the content of cell in html. The trick is easy. If the count off all states is zero, the background for div in CSS is grey. If $states[1] != 0 or in human language there is one at least of monitor in critical state, the div has a red color. If the array only have a one cell and it's the normal state, the green is in this div. And others cases, the yellow is the color for div.
  • そして残りは、セルを html に整形する処理です。仕組みは簡単です。すべての状態の合計がゼロであれば、CSS の div で背景をグレーにします。もし、$states[1] != 0 もしくは、何らかの文字で、少なくとも一つのモニタ状態が障害であれば、dev を赤にします。配列が一つのセルで正常状態であれば、div を緑にします。そして、その他の場合は、div を黄色にします。
  • Add link in the cell if count is more than 0.
  • 合計が 0 より大きければ、セルにリンクを加えます。
  • Save the row in $table, and start other iteration of foreach.
  • 行を $table に保存し、foreach で繰り返します。
  • Print the table.
  • 表を表示します。
  • Print the legend and other notes in the bottom of page.
  • 凡例とその他注意をページの下に表示します。

API 呼び出し関数

It's few lines of code. Because the operations in this lines are: これは、数行のコードです。このコードでは次のことを行います。

  • Insert the extension into Pandora menu.
  • 拡張を Pandora メニューへ挿入
And it's with the call extensions_add_operation_menu_option("Modules groups", 'estado', 'module_groups/icon_menu.png'); where:
extensions_add_operation_menu_option("Modules groups", 'estado', 'module_groups/icon_menu.png'); を呼び出すことによって行います。ここで、
  • 'Modules groups' is the name appear in submenu of agents.
  • 'Modules groups' は、エージェントのサブメニューに表示される名前です。
  • 'estado' is the element hang the extension.
  • 'estado' は、拡張に関連付けるエレメントです。
  • 'module_groups/icon_menu.png' is the image icon appear in submenu, the path is relative to your extension directory.
  • 'module_groups/icon_menu.png' は、サブメニューに表示されるアイコンです。パスは、拡張のディレクトリからの相対パスです。
  • Define the main function of this extension .
  • この拡張のメイン関数の定義
And it's with the call extensions_add_main_function('mainModuleGroups'); where:
extensions_add_main_function('mainModuleGroups'); を呼び出すことによって行います。ここで、
  • 'mainModuleGroups' is the name of extension main function.
  • 'mainModuleGroups' は、拡張のメイン関数名です。
  • Register the translate function of this extension .
  • この拡張の翻訳関数の登録
And it's with the call extensions_add_translation_string_function('extensions_translation'); where:
extensions_add_translation_string_function('extensions_translation'); を呼び出すことによって行います。ここで、
  • 'extensions_translation' is the name of extension translate function.
  • 'extensions_translation' は、拡張の翻訳関数名です。

The order of call the functions is indifferent. You can call first one and second another or any other form.

呼び出す関数の順番に指定はありません。いずれかを最初に呼び出して、2つ目に他の関数などを呼び出すことができます。

ディレクトリ構成

The directory of extension with example.

The instalation of extension is very easy, because the Pandora Console search new extensions and add into system when new extension is found. You only copy all files of extensions into the directory extension in your Pandora Console instalation. But you must set the permissions for the Pandora Console can read the files and subdirectories of extension.

extension ディレクトリの例

拡張のインストールはとても簡単です。なぜなら、Pandora コンソールは新たな拡張を検索し、それを見つけたらシステムに追加します。 拡張のファイルすべてを Pandora コンソールをインストールした extension ディレクトリにコピーするだけです。ただし、Pandora コンソールが拡張のファイルおよびサブディレクトリを読めるようにパーミッションを設定する必要があります。

In the screenshot, the extension has a directory structure: 画面例では、extension は次のようなディレクトリ構造になっています。

  • module_groups
  • icon_menu.png
  • module_groups.php

And the extension directory is for example in /var/www/pandora_console.

そして、例では extension ディレクトリは、/var/www/pandora_console にあります。

サブディレクトリ

In this case, the example has one subdirectory, and usually any extension must has one subdirectory. The subdirectory has the same name as the name extension and the main file. The subdirectory of the example only has an image icon file (icon_menu.png). This icon is shown in the Pandora Menu.

この場合、例では一つのサブディレクトリがあります。そして、通常、拡張は一つのサブディレクトリを持つ必要があります。サブディレクトリは、拡張のメインファイルと同じ名前です。この例のサブディレクトリには、アイコンファイル (icon_menu.png) のみがあります。このアイコンは、 Pandora メニューに表示されます。