Como documentar un plugin

Con el objetivo de migrar la documentación oficial de los plug-ins enterarse a esta plataforma esta es una pequeña guía de como se debe documentar un plug-in

Estructura de la documentacion

Para documentar cualquier plug-in se debe seguir una estructura básica, lo ideal es que todos los plug-in contaran con la misma estructura para dar la sensación de familiaridad y homogeneidad al usuario.

Sabemos que casa plug-in tiene su comportamiento y no todos se configuran de la misma forma, pero intentaremos hacerlos lo  más homogéneos posible.

La estructura de la documentación seria:

Describiremos cada sección a lo largo de este documento.

Introducción

En este apartado se dará una breve resumen del objetivo del plug-in, que hace y para qué sirve.

También utilizaremos este apartado para definir la última versión de revisión del documento y definir si el plug-in es de agente de servidos o cuenta con ambas opciones.

Ej:

Ver. 040521 (utilizaremos la fecha de última revisión como número de versión) 

Este documento tiene como objetivo la descripción de la monitorización de contadores de
rendimiento en entornos Windows con un servicio SQL integrado.
Para la obtención de datos se usaran los contadores de rendimiento del sistema windows, así como
consultas a través del comando sqlcmd (invoke-sqlcmd) de powershell.

Tipo: plug-in de agente

Matriz de compatibilidad

En este apartado pondremos la matriz de compatibilidad, este puede variar en función al tipo de plug-in que usemos.

Aquí debemos definir:

Por ejemplo para un plug-in escrito en PowerShell v2

Sistemas donde se ha probado

Windows Server 2008

Windows Server 2012

Windows 7
Sistemas donde debería funcionar

Windows Server 2016

Windows Server 2019

Windows 8/8.1

Windows 10
Sistemas donde no funciona Versiones anteriores a Windows server 2008 y windows 7

En este caso el plugin corre sobre el sistema operativo, pero si fuera una aplicación como mysql o postgre se deben definir las versiones de estas aplicaciones, que están comprobadas, son compatibles y las que no lo son.

Pre requisitos

En este apartado se definirán todos los requisitos necesarios para que el plug-in funcione, en el caso de los plug-ins enterprise deberán estar subidos siempre que se pueda en un binario compilado para evitar la gestión de dependencias, hay casos en los que esto no es posible o estemos documentando un plug-in open, en ese caso deben declararse en la documentación las dependencias necesarias.

En muchos casos también hay dependencias de la aplicación a monitorizar como tener un usuario (se deben definir los permisos mínimos necesarios), habilitar ciertas funcionalidades de la aplicación, tener conectividad por cierto puerto etc.

En resumen todo lo que necesitemos para que cuando ejecutemos el plug-in sea capaz de recolectar la información.

 

Ej con varis requisitos:

Despliegue de software adicional

Para la monitorización de Oracle de forma remota se requieren los siguientes paquetes instalados en su sistema:

Nota: Se ha detectado que en ciertos sistemas Solaris, puede encontrarse que los archivos descargados de la página oficial de Oracle para Instant Client generan errores al ejecutar sqlplus. Para solucionarlo, es necesario crear dos enlaces simbólicos:

cd /path/to/instantclient&sqlplus/files
ln -s `pwd` lib
ln -s `pwd` bin

Configuración de entorno

El equipo que ejecuta el plug-in requiere:

Permisos sobre las bases de datos

Se requiere un usuario y contraseña para conectar con las bases de datos. Este usuario debe tener privilegios suficientes para comprobar ciertas tablas del sistema.

Se permite la ejecución del plugin utilizando un usuario estándar o en modo SYSDBA. En todo caso será necesario especificar su password.

Para preparar los permisos del usuario sobre las bases de datos, es necesario habilitar privilegios sobre ciertas tablas. En el ejemplo siguiente se detalla cómo proporcionar acceso a tablas que el plugin utiliza por defecto.

CREATE USER pandora IDENTIFIED BY pandora;
GRANT CREATE SESSION TO pandora;
GRANT SELECT any dictionary TO pandora;
GRANT SELECT ON V_$SYSSTAT TO pandora;
GRANT SELECT ON V_$STATNAME TO pandora;
4
GRANT SELECT ON gv$sysstat TO pandora;
GRANT SELECT ON v$sesstat TO pandora;
GRANT SELECT ON V_$INSTANCE TO pandora;
GRANT SELECT ON V_$LOG TO pandora;
GRANT SELECT ON SYS.DBA_DATA_FILES TO pandora;
GRANT SELECT ON SYS.DBA_FREE_SPACE TO pandora;
GRANT SELECT ON V_$parameter TO pandora;
GRANT SELECT ON dba_tablespaces TO pandora;
GRANT SELECT ON dba_data_files TO pandora;
GRANT SELECT ON dba_free_space TO pandora;
.
.
(others GRANTs necessary, for all tables used in the plugin configuration file)
.
.
--
-- if somebody still uses Oracle 8.1.7...
GRANT SELECT ON sys.dba_tablespaces TO pandora;
GRANT SELECT ON dba_temp_files TO pandora;
GRANT SELECT ON sys.v_$Temp_extent_pool TO pandora;
GRANT SELECT ON sys.v_$TEMP_SPACE_HEADER TO pandora;
GRANT SELECT ON sys.v_$session TO pandora;

Requisitos extra

Si realiza la monitorización de Oracle DB remotamente, deberá garantizar la conectividad desde el equipo donde se ejecuta el plugin contra el servidor Oracle DB, por defecto TCP/1521.

Se requerirá conexión con el servicio Tentacle asociado a su servidor de Pandora FMS (para ejecuciones locales del plugin) bajo las siguientes condiciones:

El despliegue de este plugin por binarios no requiere ningún requisito adicional.

Configuración

En este apartado definiremos como se debe configurar el plug-in para su ejecución, aquí puede variar un poco en función a los requisitos del plug-in, por ejemplo en el caso de apache es necesario habilitar el server status como requisito por lo que es de mucha ayuda poner una breve documentación de como se hace.

En el caso de los plug-ins compilados las configuraciones vienen más por parte de la aplicación a monitorizar que del propio plug-in, al menos que necesite software extra o definición de variables de entorno como el plug-in de Oracle.

Para el caso de los plug-ins que no sea posible compilar o sean open, hay que documentar las dependencias y como obtenerlas.

Ejemplo 1: configuración de la aplicación a monitorizar

Es necesario habitar la página de server status del servidor de apache a monitorizar, en CentOS los pasos para habilitarlo son:

Ejemplo 2: Software extra necesario para el plug-in

Para la ejecución del plug-in dinamic snmp será necesario contar con snmpwalk, snmpget y snmpbulkwalk, en CentOS estas herramientas vienen disponibles con el paquete net-snmp-utils. Para instalarlo en CentOS ejecutamos:

yum install net-snmp-utils
Ejemplo 3: Dependencias necesarias por el plugin.

Para ejecutar el conector de slack  es necesario tener instalado python3 y algunas librerias de python. Para instalar python3 y el gestor de librerías en CentOS  utilizar los comandos: 

yum -y install python3 python3-pip

Al descomprimir el paquete,  verás un fichero requirements.txt donde se listan las librerías necesarias. Para instalarlas nos posicionamos en el directorio donde esta este fichero y simplemente ejecutamos:

pip3 install -r requirements.txt

Esto descargará e instalará las dependencias necesarias. Una vez instaladas las dependencias ejecutamos el fichero pandora-slack-cli.py  -h con el intérprete de Python3 para ver su ayuda:

image-1620898695868.png

Parámetros generales del plugin

En esta sección se definen los parámetros o las opciones en el fichero de configuración que son obligatorias para la ejecución del plug-in, muchos plug-ins requieren un par de parámetros obligatorios y luego muchos opcionales, aquí describiremos lo mínimo imprescindible para la ejecución, todos los parámetros opcionales los dejaremos en la sección de parámetros opcionales.

Ej: Conector Discord CLI. Necesita solo un par de parámetros para funcionar, pero opcionalmente tiene muchos más así que en esta sección definiremos los mínimos:

Como hemos visto en la ayuda, el plugin requiere de 2 parámetros obligatorios, la URL del webhook que hemos obtenido en los primeros pasos y los datos que se envían en formato clave valor separado por comas.

 

Por ejemplo: 

python3 pandora_discord_cli.py -u <webhook-url> -d "Data=5, Agent=Test, Module=Ping"

Si el envío es correcto veremos el mensaje “Message sent. status code: 200” y veremos también un tip que nos indica que si queremos enviar la gráfica de este módulo debemos pasar los parámetros de la API de pandora, por ahora lo ignoraremos. Veremos esta configuración más adelante.

 

Si vamos a nuestro chat de Discord veremos que hemos recibido el mensaje.



Parámetros específicos del plugin

En esta sección describiremos todos los parámetros opcionales del plug-in, si los tiene, todas las combinaciones y tipo de ejecuciones posibles que sean relevantes.

Ejemplo: Continuamos con el conector de Discord en este ejemplo

Parámetros opcionales

Como podemos ver, aparte de los datos serializados y la url tenemos varios parámetros opcionales, algunos son muy simples y autoexplicativos como el nombre del autor, el título, la descripción de la alerta o footer.

 

Otros son un poco menos intuitivos, como la configuración de la gráfica, así que haremos un pequeño ejemplo de una ejecución con los parámetros más relevantes. 

 

Descripción de los parámetros opcionales:

 

Parámetro

Descripción
-h, --help

Muestra la ayuda.
-d DATA, --data Los datos a enviar en pares clave=valor Ej: test=5,house=2
-u URL, --url URL Discord webhook URL
-t ALERT_TITTLE, --alert_tittle ALERT_TITTLE Título de la alerta
-D ALERT_DESC, --alert_desc ALERT_DESC Descripción de la alerta
-m MESSAGE, --message Cuerpo del mensaje
-T TITTLE_COLOR, --tittle_color TITTLE_COLOR Color del título de la alerta en hexadecimal EX: 53e514
-A AUTHOR, --author AUTHOR Nombre del autor (por defecto PandoraFMS)
-F FOOTER, --footer FOOTER Footer personalizado
--api_conf API_CONF

Parametros configuracion de la api en formato clave valor.

Ej:"user=admin,pass=pandora,api_pass=1234,api_url=http://test.artica.es/pandora_console/include/api.php"
--module_graph MODULE_GRAPH Generar una gráfica para enviar usando conexión a la api deben pasarse los parametros module_id y intervalo en formato clave valor. EX "module_id=55,interval=3600"
--tmp_dir TMP_DIR Directorio temporal donde se almacenaran las gráficas para su envio.

Al descomprimir el paquete hay un fichero test-exec.txt en el que tendremos una ejecución de ejemplo utilizando todos los parámetros:

 

python3 pandora_discord_cli.py -d "Agent=Server22,Module=test_module,Group=Servers,State=Critical,Data=22,Timestamp=2020-11-04 11:14:00" \
-u https://discord.com/api/webhooks/702868786843353179/YI1LOUzC64EcYcpPVB_ \
--tittle_color ed2512 \
--footer "PandoraFMS Alert" \
-A "Sauron Systems" \
--author_icon_url "https://pandorafms.com/wp-content/uploads/2019/04/software-de-monitorizacion-pandorafms-logo.png" \
-m "We have bad news for you. Something is on CRITICAL status 2" \
--author_url https://pandorafms.com/ \
-D "Module test is going to critical" \
--thumb https://pandorafms.com/images/alerta_roja.png \
--avatar_url https://pandorafms.com/images/alerta_roja.png \
--api_conf "user=admin,pass=pandora,api_pass=pandora,api_url=http://192.168.80.222/pandora_console/include/api.php" \
--module_graph "module_id=6266, interval=3600" \
--tmp_dir /tmp

 

El resultado de esta ejecución será ligeramente diferente, contendrá más información, indicándonos que tenemos la API configurada y que la gráfica se ha generado con éxito. 

 

Si vemos el mensaje recibido en Discord:

 

 

Veremos que es similar al anterior pero con una imagen de usuario personalizada, el logo de alerta crítica, un color de borde personalizado, título y footer y la gráfica del módulo seleccionado obtenido de la API de Pandora, simplemente pasando los parámetros correspondientes en la ejecución.

Ejecución manual

Si no se ha hecho en los dos apartados anteriores se debe describir un ejemplo de la ejecución del plug-in con los parámetros relevantes y el resultado de este en la línea de comandos.

Ej: plug-in de autodiscover de agente software.

Para la ejecución del plug-in de forma manual nos movemos a el directorio del plugin, por defecto es /usr/share/pandora_agent/plugins y ejecutamos  ./autodiscover esto nos mostrará por pantalla la ayuda del plug-in

image-1620904144211.png

Como podemos ver tenemos varias opciones que ya hemos descrito en este caso lo ejecutaremos con la opción--default

image-1620904235214.png

Como podemos apreciar, nos devuelve la estructura xml esperada para un plug-in de agente, dándonos el estado de los servicios.

Configuración en Pandora

Esta sección es importante, hay que describir de la forma más clara posible como se configura el plug-in en pandora, por lo general las opciones son plug-in de servidor, plug-in de agente o integraciones que van por alertas, pero cada caso es diferente.

Lo ideal es tener una plantilla genérica para los 3 tipos y trabajar sobre ella.

 

Colocar plantillas aquí

Módulos generados por el plugin

Por último y esta parte es muy importante es documentar el resultado del plug-in definiendo los agentes/módulos que genera y como se ve esta representación en pandora. En el caso de ser una alerta mostrar el resultado final.

Ejemplo: plug-in office 365

La ejecución estándar de este plugin devolverá un agente por cada servicio de office365 habilitado y módulos que definiremos en esta sección por defecto para cada servicio.

 

El agente y módulos usarán el prefijo definido en la ejecución o por defecto será O365

 

Agentes

recibirá como:

 

 

Monitorización (Módulos) para cada agente:

 

Ejemplo listado de agentes obtenidos por el plugin

 

Ejemplo listado de métricas para uno de los agentes

Ejemplo recolección de logs.

Para usar esta funcionalidad es necesario tener el colector de log habilitado en el entorno

Opcionalmente si se habilita la recolección de logs en los parámetros del plug-in, se capturaran todos los mensajes de incidencias relacionados con el servicio de office 365 y se almacenan en el colector de logs de Pandora referenciados en el agente O365 por defecto.