Pandora: Documentation es: Desarrollo Ampliacion

From Pandora FMS Wiki
Jump to: navigation, search

Volver a Indice de Documentacion Pandora FMS

Contents

1 Desarrollando Pandora FMS

1.1 Arquitectura general del código de Pandora FMS

1.1.1 Como hacer los links compatibles

Para todos los links, es necesario usar las función ui_get_full_url.

  • Como usar ui_get_full_url
Previamente a llamara la función es necesario incluir "functions_ui.php".
  • Cuando necesitas la URL para refrescar:
Por ejemplo
$url_refresh = ui_get_full_url();
  • Necesitas una url para un camino relativo
Por ejemplo

Método antiguo

$url = $config['homeurl'] . "/relative/path/file_script.php";

Método nuevo

$url = ui_get_full_url("/relative/path/file_script.php");
  • ¿Y en javascript? Es igual de fácil.
Por ejemplo

Método antiguo

<?php
...
$url = $config['homeurl'] . "/relative/path/file_script.php";
...
?>
<script type="text/javascript>
...
jQuery.post ('<?php $url; ?>',
 {
 ...
 });
 ...
</script>

Método antiguo

<?php
...
$url = ui_get_full_url("/relative/path/file_script.php");
...
?>
<script type="text/javascript>
...
jQuery.post ('<?php $url; ?>',
 {
 ...
 });
 ...
</script>
  • Casos especiales:
  • Los links directos hacia el index.php no es necesario usar esta función.
Por ejemplo
echo '<form method="post" action="index.php?param=111&param=222&param=333&param=444&param=555&param=666">';

1.1.2 Puntos de entrada de ejecución de Pandora Console

Pandora Console solo dispone de unos cuantos puntos de entrada de ejecución de la aplicación web.

Al contrario que otras aplicaciones web como por ejemplo Wordpress que apenas tiene un punto de entrada para el frontend y uno de backend para la administración. O el desarrollo webs de PyMEs que normalmente cada fichero php es un posible punto de entrada.

1.1.2.1 Instalación

Este punto de entrada es para realizar una instalación de Pandora Console y la base de datos. Una vez finalizada la instalación Pandora Console solicita el borrado del fichero por seguridad.

install.php

1.1.2.2 Ejecución Normal

Toda interación de los usuarios en la consola la realizan por este punto de entrada.

index.php

1.1.2.3 Peticiones AJAX

Todas las peticiones ajax por securizarlas (ya que se chequea permisos de usuario) y mantenerlas coherentes y fáciles de mantener se realizan a través de este fichero pasandole por GET o POST el parámetro page la dirección relativa del script a ejecutar.

ajax.php

1.1.2.4 Consola movil

Para los terminales móviles que disponen de una pantalla sensiblemente mas pequeña que el monitor de un ordenador, Pandora FMS dispone de una versión reducida de la consola para estos dispositivos, reducida tanto en aspecto visual como simplificada la funcionalidad ya que estos dispositivos tampoco disponen de una interfaz de uso optima.

mobile/index.php

1.1.2.5 API

Desde la versión Pandora FMS 3.1 dispone de una API de tipo REST con la que terceras aplicaciones pueden interaccionar a través de un canal simple por el puerto 80 y con el protocolo HTTP.

La securización de este script es por medio de tres parámetros, validando los tres:

  • Que la IP del cliente que lo ejecuta este en la lista de IPs validas seteadas en el setup de Pandora Console o machee con la expresión regular también guardada en el mismo lugar.
  • Que le hayan pasado por parámetro el API password que se setea también en el setup de Pandora Console.
  • Que le pase por parámetro el user y el password del usuario que va a realizar la acción del API.
include/api.php

1.1.2.6 Casos especiales

Dentro de Pandora Console hay varios casos especiales para puntos de entrada, normalmente por evitar login o procesamientos generales que se hacen en el punto de entrada principal (index.php del raiz).

1.1.2.6.1 Extensión Tareas Cron

Esta extensión por medio de un comando wget en el cron puede ejecutar las tareas de cron que se le han asignado sin pedir login de forma interactiva. Por supuesto el conjunto de tareas esta delimitado y conocido impidiendo la ejecución de código malicioso sin login.

enterprise/extensions/cron/cron.php
1.1.2.6.2 Consola visual vista externa

Este genera una página con la vista de una consola visual a pantalla completa sin ser necesario un login, aunque para autentificación si es necesario un hash generado para cada vista que se publique de esta manera.

operation/visual_console/public_console.php
1.1.2.6.3 Consola Networkmap Popup detalle

Un popup que muestra la vista en detalle de un agente que tiene un item en el Consola Networkmap. Usa para autentificarse la session del usuario que se ha logueado en el Pandora Console.

enterprise/operation/agentes/networkmap_enterprise.popup.php
1.1.2.6.4 Gráfica de módulos Popup

Un popup que muestra una gráfica de un modulo al detalle y que permite también configurar varios parámetros de visualización. Usa para la autenticación los datos el usuario que se ha logueado en el Pandora Console.

operation/agentes/stat_win.php
1.1.2.6.5 Gráficas estáticas

Las gráficas estáticas son ficheros de imagen que se generan por medio de scripts PHP, los datos a mostrar, si son extensos se guardan serializados en un fichero especial que procesa el script, este fichero tiene un tiempo de vida para evitar accesos maliciosos y ataques por DOS. Para la ejecución de este script no es necesario estar autentificado en Pandora.

include/graphs/fgraph.php
1.1.2.6.6 Informes
1.1.2.6.6.1 Informe en CSV

El script genera un fichero de texto que contiene los datos CSV, para la autentifación usa los datos del usuario logueado.

enterprise/operation/reporting/reporting_viewer_csv.php

1.1.2.6.6.2 Informe en PDF

El script genera un fichero de texto que contiene los datos PDF, para la autentifación usa los datos del usuario logueado.

enterprise/operation/reporting/reporting_viewer_pdf.php


1.1.2.6.7 Eventos
1.1.2.6.7.1 Eventos sonoros Popup

Ventana de Popup que esta chequeando periodicamente si existe algún evento para mostrarlo de forma sonora y visual, la autentificación es por medio de los datos del usuario logueado.

operation/events/sound_events.php

1.1.2.6.7.2 Eventos en CSV

El script genera un fichero de texto que contiene los datos CSV, para la autentifación usa los datos del usuario logueado.

operation/events/export_csv.php

1.1.2.6.7.3 Marquesina de eventos

Ventana de popup que muestra una marquesina con los eventos de Pandora. Para la autentificación usa el API password.

operation/events/events_marquee.php

1.1.2.6.7.4 Eventos en RSS

El script genera un fichero de texto que contiene los datos CSV, para la autentifación usa los datos del usuario logueado en un hash que va como parametro.

operation/events/events_rss.php

1.2 Funciones básicas para obtener estado de agente, modulo y grupos

1.2.1 Criterio para Estados y codificación en la base de datos

Descripción de estados del agente:

  • Crítico (color rojo): 1 o más módulos en estado crítico.
  • Adventencia (color amarillo): 1 o más módulos en estado advertencia y ninguno en estado crítico.
  • Desconocido (color gris): 1 o más módulos en estado desconocido y ninguno en estado crítico y advertencia.
  • Normal (color verde): todos los módulos están en estado nomal.

Código interno del estado en la BBDD:

  • Crítica: 1
  • Advertencia: 2
  • Desconocida: 3
  • Normal: 0

1.2.2 Agentes

1.2.2.1 Funciones de Estado

Estas funciones devuelven el número de módulos y alertas disparadas de un agente aplicando un filtro de forma opcional.

Todas las funciones tienen la opción filter que fue añadido para hacer la función más flexible. El contenido del filtro se añade al final de la consulta sql en todas las funciones. Con el filtro puede añadir claúsulas sql específicas para crear filtros usando las tablas: tagente_estado, tagente y tagente_modulo.

  • agents_monitor_critical ($id_agent, $filter=""): Devuelve el número de módulos en estado crítico para el agente.
  • agents_monitor_warning ($id_agent, $filter=""): Devuelve el número de módulos en estado advertencia para el agente.
  • agents_monitor_unknown ($id_agent, $filter=""): Devuelve el número de módulos en estado desconocido para el agente.
  • agents_monitor_ok ($id_agent, $filter=""): Devuelve el número de módulos en estado normal para el agente.
  • agents_get_alerts_fired ($id_agent, $filter=""): Devuelve el número de alertas disparadas para el agente.

1.2.2.2 Funciones auxiliares

Estas funciones realizan tareas relacionadas con los agentes para algunas vistas:

  • agents_tree_view_alert_img ($alert_fired): Devuelve la ruta de la imagen de alerta usada en la vista Tree View.
  • agetns_tree_view_status_img ($critical, $warning, $unknown): Devuelve la rutta de la imagen para el estado del agente usada en al vista Tree View.

1.2.3 Grupos

Estas funciones devuelven las estadísticas de agentes y módulos para los grupos de agentes definidos en Pandora.

Template warning.png

¡Ten cuidado! Las funciones del servidor y la consola deben usar las mismas consultas sql para asegurar que el resultado es calculado de la misma forma

 


1.2.3.1 Funciones del servidor

  • pandora_group_statistics: Esta función calcula las estadísticas de grupo si el parámetro Use realtime statistics está desactivado.

1.2.3.2 Funciones de la consola

Las funciones de la consola calculan las estadísticas en base a un array de grupos de agentes. Estas funciones no usan los agentes o módulos deshabilitados.

  • groups_agent_unknown ($group_array): Devuelve en número de agentes en estado desconocido para los grupos dados.
  • groups_agent_ok ($group_array): Devuelve en número de agentes en estado normal para los grupos dados.
  • groups_agent_critical ($group_array): Devuelve en número de agentes en estado crítico para los grupos dados.
  • groups_agent_warning ($group_array): Devuelve en número de agentes en estado advertencia para los grupos dados.

Estas funciones calculan las estadísticas para los módulos. No usan los módulos o agentes deshabilitados.

  • groups_monitor_not_init ($group_array): Devuelve el número de módulos con estado non inicalizado para los grupos dados.
  • groups_monitor_ok ($group_array): Devuelve el número de módulos con estado normal para los grupos dados.
  • groups_monitor_critical ($group_array): Devuelve el número de módulos con estado crítico para los grupos dados.
  • groups_monitor_warning ($group_array): Devuelve el número de módulos con estado advertencia para los grupos dados.
  • groups_monitor_unknown ($group_array): Devuelve el número de módulos con estado desconocido para los grupos dados.
  • groups_monitor_alerts ($group_array): Devuelve el número de módulos con alertas para los grupos dados.
  • groups_monitor_fired_alerts ($group_array): Devuelve el número de módulos con alertas disparadas para los grupos dados.

1.2.4 Módulos

Estas funcions devuelve las estadísticas en base al nombre del módulo. No tiene en cuenta los agentes y módulos deshabilitados.

  • modules_agents_unknown ($module_name): Devuelve el número de agents en estado desconocido que tienen un módulo con el nombre dado.
  • modules_agents_ok ($module_name): Devuelve el número de agents en estado normal que tienen un módulo con el nombre dado.
  • modules_agents_critical ($module_name): Devuelve el número de agents en estado crítico que tienen un módulo con el nombre dado.
  • modules_agents_warning ($module_name): Devuelve el número de agents en estado advertencia que tienen un módulo con el nombre dado.

Estas funciones devuelven las estadísticas usando como filtro el grupo de módulo. No tiene en cuenta agentes o módulos deshabilitados.

  • modules_group_agent_unknown ($module_group): Devuelve el número de agentes con estado desconocido que tienen módulos que pertenecen al grupo de módulos dado.
  • modules_group_agent_ok ($module_group): Devuelve el número de agentes con estado normal que tienen módulos que pertenecen al grupo de módulos dado.
  • modules_group_agent_critical ($module_group): Devuelve el número de agentes con estado crítico que tienen módulos que pertenecen al grupo de módulos dado.
  • modules_group_agent_warning ($module_group): Devuelve el número de agentes con estado advertencia que tienen módulos que pertenecen al grupo de módulos dado.

1.2.5 Políticas

Estas funciones devuelven el número de agentes para cada estado y política dada. No usan los agentes y módulos deshabilitados para calcular el resultado.

  • policies_agents_critical ($id_policy): Devuelve el número de agentes con estado crítico que pertenecen a una política dada.
  • policies_agents_ok ($id_policy): Devuelve el número de agentes con estado normal que pertenecen a una política dada.
  • policies_agents_unknown ($id_policy): Devuelve el número de agentes con estado desconocido que pertenecen a una política dada.
  • policies_agents_warning ($id_policy): Devuelve el número de agentes con estado advertencia que pertenecen a una política dada.

1.2.6 OS

Estas funciones calculan las estdísticas para los agentes en base los Sistemas Operativos a los que pertenecen. No usan agentes o módulos deshabilitados.

  • os_agents_critical ($id_os): Devuelve el número de agentes en estado crítico que pertencen al Sistema Operativo dado.
  • os_agents_ok($id_os): Devuelve el número de agentes en estado normal que pertencen al Sistema Operativo dado.
  • os_agents_warning ($id_os): Devuelve el número de agentes en estado advertencia que pertencen al Sistema Operativo dado.
  • os_agents_unknown ($id_os): Devuelve el número de agentes en estado desconocido que pertencen al Sistema Operativo dado.

1.3 Desarrollo y ampliación

La mayoría de las ampliaciones han sido descritas como anexos independientes, especializados para creación de plugin de servidor, plugins de agente Unix, y extensiones de la consola. En este capítulo se describe como colaborar en Pandora FMS y como compilar el agente de Windows desde las fuentes. En el futuro, cualquier otro tema relacionado con el desarrollo que no tenga un apéndice específico pasará a engrosar este capítulo.

1.3.1 Colaborar con el proyecto Pandora FMS

Este proyecto lo mantienen desarrolladores voluntarios con sus colaboraciones. Nuevos desarrolladores, redactores de documentación, o gente que quiera ayudar será siempre bienvenida. Una buena manera de empezar es subscribéndose a nuestras listas de correo y/o al foro.

1.3.2 Subversion (SVN)

El desarrollo de Pandora FMS se hace mediante SVN (code revision control system). Se puede encontrar más información acerca de cómo entrar a los repositorios de SVN en: OpenIdeas Wiki. Nuestro sistema de SVN es público y está alojado en Sourceforge:

Usando la línea de comandos del cliente de SVN:

svn co https://svn.code.sf.net/p/pandora/code/ pandora

1.3.3 Bugs / Fallos

Informar acerca de posibles errores nos ayuda a mejorar Pandora FMS. Por favor, antes de enviar un informe de error, revisa nuestra base de datos de bugs y en caso de detectar uno no reportado, envíalo usando la excelente herramienta de Sourceforge para seguimiento e informe de fallos en la WEB del proyecto: http://sourceforge.net/projects/pandora/

1.3.4 Listas de correo

Las listas de correo son una excelente manera de mantenerse al día por correo electrónico. Tenemos una lista de correo pública para usuarios y anuncios (con poco tráfico) y una lista de correo de desarrollo para discusiones técnicas y notificaciones (a veces diarias) del desarrollo mediante el sistema automático de notifiación de nuestro SVN (Sistema de control de versión de código).

1.4 Compilación del agente de Windows desde el código

1.4.1 Obtener la última versión del código

Para obtener la última versión del código es imprescindible hacerlo descargando las fuentes del repositorio de código SubVersion de Sourceforge, donde tenemos publicado el repositorio oficial de Pandora FMS. Para ello, necesita instalar un cliente de Subversion. Cuando lo tenga listo, ejecute lo siguiente desde la línea de comandos:

svn co https://svn.sourceforge.net/svnroot/pandora pandora

1.4.2 Compilación desde Windows

Para compilar/linkar desde las fuentes, necesitará obtener la última version del entorno de desarrollo (IDE) Dev-CPP, que incluye a su vez el compilador MinGW. Descárguela desde este enlace.

Abra el fichero PandoraAgent.dev con Dev-CPP y construya el proyecto. Después de ajustar diferentes parámetros (paths principalmente), deberia ser capaz de compilar el agente Windows.

Si encuentra problemas al compilar desde las fuentes, contacte directamente con el jefe de desarrollo del equipo Windows: (ramon.novoa @ artica . es) o bien a través de nuestra página WEB de Sourceforge.

1.4.3 Compilación cruzada desde Linux

Para lograr una compilación cruzada (esto significa crear el ejecutable nativo de Windows desde un entorno Linux), necesita seguir los siguientes pasos:

1.4.3.1 Instale el compilador WinGW para Linux

Para entornos Ubuntu/debian:

sudo aptitude install mingw32

Para entornos SUSE o RPM compatibles, puede hacerlo con zypper o manualmente con esta URL:

http://download.opensuse.org/repositories/CrossToolchain:/mingw/openSUSE_11.1/

1.4.3.2 Instalación de las librerias e includes extras que necesita el agente

Por ejemplo, para instalar el paquete de librias OpenSSL, vaya a http://sourceforge.net/projects/devpaks/files y descarge el fichero:

openssl-0.9.8e-1cm.DevPak

Descomprima el fichero openssl-0.9.8e-1cm.DevPak:

tar jxvf openssl-0.9.8e-1cm.DevPak

Copie las librerías e includes a su entorno de compilacion cruzada con MinGW:

cp lib/*.a /usr/i586-mingw32msvc/lib/
cp -r include/* /usr/i586-mingw32msvc/include/

Descargue e instale los paquetes 'autogen' y 'autoconf'

sudo apt-get install autogen autoconf

Vaya al directorio donde se encuentran las fuentes del agente de Windows y ejecute:

./autogen.sh

Existe una alternativa, mas rápida, cómoda y fácil, pero necesitará resolver posibles problemas de dependencias y versiones usted solo. Hemos hecho un tarball con todas las librerias e includes necesarias y las hemos subido al sitio WEB oficial con el nombre de mingw_pandorawin32_libraries_9Oct2009.tar.gz

1.4.3.3 Compilación y linkado

Después de instalar el compilador, vaya al directorio donde se encuentran las fuentes del agente de Windows y ejecute

./configure --host=i586-mingw32msvc && make

Esto debería compilar y linkar el ejecutable del agente de Pandora FMS para Windows.

1.5 API de Pandora FMS

Existe una API externa de Pandora FMS para poder enlazar terceras aplicaciones con Pandora FMS, tanto para obtener información de Pandora FMS como para introducir información dentro de Pandora FMS. Toda esta documentación está en el apéndice de API Externa de Pandora FMS. Puede encontrar mas documentación en Pandora:Documentation es:Anexo API external.

1.6 Formato de los ficheros de datos XML

Conocer el formato de los XML de datos de Pandora FMS te puede ayudar a mejorar los plugins de agente, crear agentes personalizados o simplemente enviar ficheros XML personalizados al servidor de datos de Pandora FMS.

Como cualquier documento XML, el fichero de datos debería comenzar con una declaración XML:

 <?xml version='1.0' encoding='UTF-8'?>

A continuación viene el elemento agent_data que define al agente que envía los datos. Soporta los siguientes atibutos:

  • description: Descripción del agente.
  • group: Nombre del grupo al que pertenece el agente (debe existir en la base de datos de Pandora FMS). Si se deja vacío y no hay un grupo configurado por defecto en el servidor, el agente no se creará.
  • os_name: Nombre del sistema operativo en el que corre el agente (debe existir en la base de datos de Pandora FMS).
  • os_version: Cadena libre que describe la versión del sistema operativo.
  • interval: Intervalo del agente (en segundos).
  • version: Cadena con la versión del agente.
  • timestamp: Marca de tiempo que indica cuándo se generó el XML (YYYY/MM/DD HH:MM:SS).
  • agent_name: Nombre del agente.
  • timezone_offset: Desplazamiento que se suma a la marca de tiempo (en horas). Útil si se trabaja con UTC.
  • address: Direccion IP del agente ( o FQN ).
  • parent_agent_name: Nombre del padre del agente.

A partir de la version 5.1 se pueden añadir los siguientes parámetros:

  • custom_id: ID personalizado del agente.
  • url_address: URL de acceso al agente.

Veamos un ejemplo de la cabecera XML:

 <agent_data description= group= os_name='linux' os_version='Ubuntu 10.10' interval='30' version='3.2(Build 101227)' timestamp='2011/04/20 12:24:03' agent_name='foo' timezone_offset='0' parent_agent_name='too' address='192.168.1.51' custom_id='BS4884' url_address='http://mylocalhost:8080'>

A continuación necesitamos un elemento module por cada módulo, y se pueden anidar los siguientes elementos para definir el módulo:

  • name: Nombre del módulo.
  • description: Descripción del módulo.
  • tags: Etiquetas asociadas al módulo.
  • type: Tipo del módulo (debe existir en la base de datos de Pandora FMS).
  • data: Dato del módulo.
  • max: Valor máximo del módulo.
  • min: Valor mínimo del módulo.
  • post_process: Valor de pos-procesado.
  • module_interval: Intervalo del módulo (intervalo en segundos / intervalo del agente).
  • min_critical: Valor mínimo para el estado crítico.
  • max_critical: Valor máximo para el estado crítico.
  • min_warning: Valor mínimo para el estado de alerta.
  • max_warning: Valor máximo para el estado de alerta.
  • disabled: Deshabilita (0) o habilita (1) el módulo. Los módulos deshabilitados no se procesan.
  • min_ff_event: Umbral de FF (ver [1]).
  • status: Estado del módulo (NORMAL, WARNING or CRITICAL). Los límites de los estados crítico y de alerta se ignoran si se especifica el estado.

Cualquier otro elemento se salvará como información extendida del módulo en la base de datos de Pandora FMS:



Module extended info.png



Un módulo deberá tener al menos un elemento name, type y data.

Por ejemplo:

 <module>
   <name>CPU</name>
   <description>CPU usage percentage</description>
   <type>generic_data</type>
   21
 </module>

Puede haber cualquier número de elementos en un fichero de datos XML. Por último, ¡no hay que olvidar cerrar la etiqueta agent_data!

Hay un caso especial de XML multi item, basado en una lista de datos. Esto se aplica únicamente a datos de tipo cadena. El XML sería algo parecido a esto:

 <module>
 <type>async_string</type>
 <datalist>
   <value><![CDATA[xxxxx]]></value>
   <value><![CDATA[yyyyy]]></value>
   <value><![CDATA[zzzzz]]></value>
 </datalist>
 </module>

Se puede especificar una marca de tiempo para cada valor:

 <module>
 <type>async_string</type>
 <datalist>
   
     <value><![CDATA[xxxxx]]></value>
     <timestamp>1970-01-01 00:00:00</timestamp>
   
   
     <value><![CDATA[yyyyy]]></value>
     <timestamp>1970-01-01 00:00:01</timestamp>
   
   
     <value><![CDATA[zzzzz]]></value>
     <timestamp>1970-01-01 00:00:02</timestamp>
   
 </datalist>
 </module>

Veamos algunos ejemplos más que incluyen el uso de umbrales y de unidades:

<module>
        <name><![CDATA[Cache mem free]]></name>
        <description><![CDATA[Free cache memory in MB]]></description>
        <tags>tag</tags>
        <type>generic_data</type>
        <module_interval>1</module_interval>
        <min_critical>100</min_critical>
        <max_critical>499</max_critical>
        <min_warning>500</min_warning>
        <max_warning>600</max_warning>
        <unit><![CDATA[MB]]></unit>
        <data><![CDATA[3866]]></data>
</module>

<module>
        <name><![CDATA[Load Average]]></name>
        <description><![CDATA[Average process in CPU (Last minute) ]]></description>
        <tags>tag</tags>
        <type>generic_data</type>
        <module_interval>1</module_interval>
        <data><![CDATA[1.89]]></data>
</module>

Volver a Indice de Documentacion Pandora FMS