Pandora: Documentation es: Anexo ConsoleExtensions

From Pandora FMS Wiki
Jump to: navigation, search

Volver a Indice de Documentacion Pandora FMS

1 Desarrollo de extensiones de la Consola

Extensiones son una manera de desarrollar una nueva funcionalidad para su Pandora Console como plugins.

En este capítulo aprenderá como desarrollar una extensión:

1.1 Tipos de Extensiones

Una extensión puede ser alguno de los tipos o varios a la vez:

  • Pestaña agente, extensiones que aparecen en el la cabecera de pestañas de la vista de operación o y edición del agente.
  • Visibles,extensiones que aparecen en el Menú de Pandora.
  • Invisibles, extensiones que se cargan y ejecutan en el index.php del Menú de Pandora pero que no aparecen en el Menú de Pandora.

1.2 Directorio de Extensiones

El directorio de extensiones es un subdirectorio dentro de su instalación local de la consola de Pandora que tiene el nombre de "extensiones". Este directorio contiene lo siguiente para cada extensión:

Fichero principal de la extensión
este fichero tiene el código que se ha de cargar en la consola de Pandora
Subdirectorio de extensión
es opcional y puede contener el fichero de imagen del icono( 18x18) que se muestra al lado del nombre de la extensión en el menú, así como otros ficheros como traducciones, módulos e imagenes.


1.3 Estructura de la extensión

<?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 */
extensions_add_operation_menu_option ('< Name Extension >', '< father ID menu >', '< relative path Icon >');

/* Adds the link in the godmode menu */
extensions_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 */
extensions_add_main_function ('< name of main function >');

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

1.4 API para Extensiones

Template warning.png

El API para extensiones está todavía en desarrollo y puede cambiar en el futuro

 


Puede obtener más información sobre el API en pandora-develop mailng list o en el forum.

Las siguientes secciones que contienen la descripción de las funciones en el API para extensiones son:

1.4.1 extensions_add_operation_menu_option

extensions_add_operation_menu_option ('< string name >', '< father ID menu >', '< relative path Icon >'):esta funcion añade el link a la extension con el nombre dado en el menú Operaciones. El tercer parámetro es opcional y este es el campo opcional para que la imagen de icono(18x18 pixels)aparezca al lado del link. Si este parámetro no está definido, se utilizará el icono de un enchufe.

1.4.2 extensions_add_godmode_menu_option

extensions_add_godmode_menu_option ('< Name Extension >', '< ACL level >' , '< father ID menu >', '< relative path Icon >'): Esta función añade el link a la extensión con el nombre dado en el menu Godmode si el usuario tiene el nivel de ACL requerido tal y como indica el segundo parámetro. El cuarto parámetro es opcional y es el campo relativo para que ala imagen del icono( 18x18 pixels) aparezca al lado del link. Si este parámetro no está definido, se utilizará el icono de un enchufe.(Extensions.png)


1.4.3 extensions_add_main_function

extensions_add_main_function ('< name of main function >'): fija la función callback que devolverá cuando el usuario haga click en el link de la extensión del menú operación.

1.4.4 extensions_add_godmode_function

extensions_add_godmode_function ('< name of godmode function >'): añade la función de extensión para llamar una vez que el usuario vaya a la extensión en el godmode de la consola de Pandora en lugar de cargar la función_principal.


1.4.5 extensions_add_login_function

extensions_add_login_function ('< name of login function >'): añade la función de extensión para llamar una vez que el usuario se loge correctamente en la consola de Pandora.

1.4.6 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 >'): añade una pestaña mas a la vista de edición del agente que cuando se selecciona se ejecuta el código de la función del nombre que se le pasa.

1.4.7 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 >'): añade una pestaña mas a la vista de operación del agente que cuando se selecciona se ejecuta el código de la función del nombre que se le pasa.

1.4.8 extensions_add_translation_string_function (>= 7.0)

extensions_add_translation_string_function('< Name of translation function >'): añade la función de callback que será llamada desde la función estándar de traducción de extensiones, ___().

1.4.9 Father IDs en el menú

Lista de stings IDs disponibles para usar en extensión API. Si utiliza un valor nulo o no incluye parámetro en la función call, entonces la extensión aparece únicamente en el submenú de extensión

1.4.9.1 Operación

  • 'estado': Vista de monitorización
  • network: Vista de redes
  • reporting: Informes y visualización de datos
  • gismaps: Vista GIS
  • eventos: Vista de eventos
  • workspace: Espacio de trabajo del usuario

1.4.9.2 Administration

  • 'gagente': Gestión de la monitorización
  • gmassive: Operaciones masivas
  • 'gmodules': Gestión de móudulos
  • 'galertas': Gestión de alertas
  • 'gusuarios': Gestión de usuarios
  • 'godgismaps': Gestión GIS
  • 'gserver': Gestión de servidores
  • 'glog': Logs del sistema
  • 'gsetup': Configuración
  • 'gdbman': Mantenimiento BBDD
1.4.9.2.1 Administration Enterprise

Info.png

Estos elementos sólo están disponibles con la versión Enterprise

 


  • gpolicies: Gestión de políticas

1.5 Ejemplo



Screenshot example.png



La extensión muestra una tabla donde las columnas son grupos de módulos y las filas grupos de agentes. Cada celda tiene un color con los siguientes significados:


  • Verde: cuando todos los módulos del grupo estan OK.
  • Amarillo: cuando existe al menos un monitor en alerta.
  • Rojo: cuando al menos un monitor falla.

Y esta extensión cuelga del menu Operación en Agentes.

1.6 Código fuente

<?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');
?>

1.7 Explicación

En el código fuente existen dos partes:

  • El código fuente de la extensión.
  • Las funciones de llamada API.

El orden de las partes es indiferente, pero es mejor poner las "funciones API de llamada" debajo de tu fichero principal de extensión por que las guias de estilo advierten que se debe situar esta parte debajo para que todas las extensiones tengan aproximadamente el mismo estilo.


1.7.1 Código fuente de extensión

En el caso de este ejemplo hay dos funciones en el mismo fichero, pero si usted tiene un código más complejo, entonces es mejor dividirlo en muchos ficheros (y guardarlo en extensión de subdirectorio). Las funciones son:

  • función extensions_translation() (>= 7.0)
Función específica para la extensión de traducciones. Se le llama desde la función principal de traducciones, ___() (tres '_'. no __()).
  • función de traducción(&$item, $key)
El uso de esta función para callback en array_walk function.Debido a que la función principal mantiene los títulos de las columnas y los títulos de las filas seleccionados sin traducciónes
  • función mainModuleGroups()
Es el núcleo de la extensión y tiene una enorme cantidad de líneas. No se visualiza todo el código, pero sí algunas partes importantes:
  • La primera es el acceso al global var config. En este var tiene muchas configuraciones y valores por defecto para muchos elementos de la consola de Pandora.
  • El segundo var es el query en MySQL en un string. Y el %d es el format placeholders es para Id Groupy Id Module Groupy estos son sustitutos para el valor en sprintf function en
  • Algunos echos para imprimir el texto delante de la tabla
  • Extracto de dos selecciones de la BD con una dimensión con el índice como id y el contenido como título para columnas (Module groups) y filas (Agent group).
  • Traduce los títulos de la seleccion del Model Group.
  • Hace estable el meta-object rellena con filas e imprime.
  • Delante de los foreach loops, define como $table la cabecera y estilos de la tabla.
  • El primer loop es para las filas (cada grupo de agentes).
  • El segundo loop es para las columnas en hilera normal(cada grupo de módulos).
  • Después, para cada celda, hay dos números, id model group e id agent group.Con estos dos números haremos una query a la base de datos y obtendremos los ficheros.
  • Procesa la selección resultante para obtener otra selección y el indice es una integración de diferentes tipos de estado de monitor y el contenido es un cómputo del monitor en ese estado.
  • Lo único que queda por hacer es rellenar el contenido de la celda en html. El modo de hacerlo es sencillo:si el cómputo de todos los estados es cero, el background para div en CSS es gris. Si $states[1] != 0 ó existe al menos un monitor en estado crítico , entonces el div tendrá un color rojo. Si la selección tiene sólo una celda y está en modo normal entonces el color verde estará en esta div. En los otros casos el amarillo será el color para div.
  • Añadir un link en la celda si el cómputo es mayor que 0.
  • Guardar la serie en $table, y empezar otra iteration de foreach.
  • Imprimir la tabla.
  • Imprimir la leyenda y otras notas en la parte inferior de la página.

1.7.2 API calls functions

Hay pocas líneas de código.Las operaciones en estas líneas son:

  • Insertar la extensión en el menu de Pandora.
Y aparece como extensions_add_operation_menu_option("Modules groups", 'estado', 'module_groups/icon_menu.png'); donde:
  • 'Modules groups' es el nombre que aparece en el submenú de agentes.
  • 'estado' el el elemento que cuelga de la extensión.
  • 'module_groups/icon_menu.png'es el icono de la imagen que aparece en el submenu, el compo está relacionado con el directorio de extensión que usted tenga..
  • Define la función principal de esta extensión.
Y aparece como extensions_add_main_function('mainModuleGroups'); donde:
  • 'mainModuleGroups' es el nombre de la función principal de la extensión.

El orden para nombrar las funciones es indiferente.

1.7.3 Organización del Directorio



Directory extension example.png



La instalación de la extensión resulta muy fácil, ya que la consola de Pandora busca nuevas extensiones y las añade al sistema cuando las encuentra.

Únicamente deberá copiar todos los ficheros de extensiones a la extension del directorio en su instalación de Pandora Console. Pero debe instalar los permisos para que la consola de Pandora pueda leer los ficheros y los subdirectorios de extensión.

En el pantallazo la extensión tiene esta estructura de directorio:

  • module_groups
  • icon_menu.png
  • module_groups.php

Y la extension del directorio está por ejemplo en /var/www/pandora_console.

1.7.4 Subdirectorio

En este caso, el ejemplo tiene un subdirectorio y generalmente cualquier extensión debe tener un subdirectorio. El subdirectorio tiene el mismo nombre que el nombre de la extension y el fichero principal. El subdirectorio del ejemplo tiene sólo un fichero de imagen de icono(icon_menu.png). Este icono aparece en el Menú de Pandora.

Volver a Indice de Documentacion Pandora FMS