# Como documentar un plugin # 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: - Introducción - Matriz de compatibilidad - Prerrequisitos - Configuración - Parámetros generales del plugin - Parámetros específicos del plugin - Ejecución manual - Configuración en Pandora - Módulos generados por el plugin 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: - Sistema y versión contra el que se ha probado y sabemos que funciona - Sistemas donde teóricamente debería funcionar - Sistemas en los que se sabe que no funciona. 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: - Oracle instantclient (basic) instalado. - Oracle-instantclient (sqlplus) instalado. 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: - SQLPLUS está disponible. - El comando ‘lsnrctl’ está disponible (en monitorización local). - Acceso al puerto donde Oracle está escuchando (en monitorización remota) - Variables Oracle exportadas al entorno del usuario que ejecuta el plugin. El usuario deberá pertenecer al grupo sistema Oracle. - Acceso a la ubicación de los logs de alertas (solo local). - Importante, el PATH a los binarios de SQLplus y lsnrctl deben estar disponibles para el usuario que ejecuta el plugin. - El usuario que ejecuta el plugin debe pertenecer al grupo de explotación de la base de datos, para poder tener acceso al fichero tnsnames.ora. **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: - Si tiene as\_server\_plugin habilitado. - Si tiene agent\_per\_instance habilitado. 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: - - pasos - para - habilitarlo ##### **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](https://pandorafms.com/guides/public/uploads/images/gallery/2021-05/scaled-1680-/image-1620898695868.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-05/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 -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. ![](https://lh5.googleusercontent.com/rLUVhwlAw5YV0RgGbCnB1n0djEoJyQfNyCByhSWr83Bx9N0eGXEtIuoA6_hxLokJGFT6wXf0byewjA_jwmhTvURbfEilCDaEhbHDSJDtiWCnQmaFrKyXhgWg_wiHHBNX3_mpf2Wo) **Si vamos a nuestro chat de Discord veremos que hemos recibido el mensaje.** ![](https://lh5.googleusercontent.com/YQuvyMWfiqJDsnLPSk7x6igNhx1Yg8l2ljUCSaKc02D6zhSwwERuwlPQtkP0d6_rlYsx8oXgJY0fXT3oiCIsTnsbCMUYfrWbkeUfpE_tyw_gAjbfaMEISxC_EKzAHXn0un8b-a5z) # 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 ``` ![](https://lh3.googleusercontent.com/AO3wxFKbHLC2PFEneUbEPkt2EDtc5zpA069-qYABlRoXLAevOtjpDZs2riX5ng4J-eqcGth0oee_TxnIRN_PN3UovvRW0226exhiudGT6JH6vApSRIxcjzu85E56jBeZ-CcLMNJb) 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: ![](https://lh3.googleusercontent.com/-R9_VkWPeIu8H6tAYJZRpvX14n3ODRO4w9ONeUjGbMlerXFSz6Tt_N2bYM503U2Yzcyx0dDvmv2m_sh4UhSIzHiO8VQSjoi0aLJWJ4RkQOp9-Bb0EMYvt0XjIrzhqfJHsUiKgtxZ) 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](https://pandorafms.com/guides/public/uploads/images/gallery/2021-05/scaled-1680-/image-1620904144211.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-05/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](https://pandorafms.com/guides/public/uploads/images/gallery/2021-05/scaled-1680-/image-1620904235214.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-05/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: - **Alias**: prefijo <nombre descriptivo del servicio - **Nombre**: prefijo\_<id del servicio> - **Intervalo**: El definido en la ejecución o por defecto 300 - **Grupo**: el definido en la ejecución o por defecto unknown Monitorización (Módulos) para cada agente: - Estado general del servicio. - Estado detallado de cada feature del servicio. - Listado de Ids de incidentes (si existen). ### Ejemplo listado de agentes obtenidos por el plugin ![](https://lh3.googleusercontent.com/BnLmsIi-pgDK2g3Egt6BiC4a4bpFNvq7oKMwOZil7n7a4q8NdGKimUGv62UiHSYTH5xrG7LPwjUIogNEJ-OJd2WcnrLoZGgRjDLlQBLq6bj0qUbWgAXztby9OG9ukI_Zy_hRdRn7) ### Ejemplo listado de métricas para uno de los agentes ![](https://lh6.googleusercontent.com/ldEAU415aybiXGMymr5-knrxzB8Kqyhv7hmLUVtDTVe-gwyRsn7FkMMMo4bvJpKfGeEvdu5XpMH2BQ5ipOdN6bHNFpF3TXWdFP8gBCJH9YkJlQg23zqEMEooTa52MxpJuLANnxn2) ### 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. ![](https://lh4.googleusercontent.com/ENGSXOnB3_ZLwIrkeGNgDusI1zOhcdeUVKf9SYpxZpFabXvPFSLS5kHcK4uC6K4ctchhQ_ind4wqGZL0TnvTbX-h8YlOvhbawrHMuIYmT3GES5i-QRhFTd9hvI05zegkIo5uZVr8) ![](https://lh5.googleusercontent.com/zLWFO2v3L5lLhaAUEEIbCgfDEK-KKxjnoDQnVZSHxlNvdc6repLes8zihj9YihZQH5pqCqiFP-1Sa1CdGtePStDmsewmLXiBTEjkgzzMpO1yfTjC7rqW29t_6XhNb99Qvm8A4lSq)