Plugin de Mist

• Introducción
• Matriz de compatibilidad
• Pre-requisitos
• Configuración
• Ejecución del plugin y parámetros
• Cómo crear un apitoken de Mist
• Cómo saber el "Organization ID"
• Configuración en Pandora FMS
• Módulos generados por el plugin

Introducción

Ver. 130721

Este plugin se usará para monitorizar los dispositivos dados de alta en el Cloud de Mist.

Conecta con el servicio del Cloud de Mist para obtener los datos de las zonas registradas y los dispositivos en cada zona, y envía esta información al servidor de Pandora FMS en el que se ha ejecutado el plugin.

Tipo: Plugin de servidor.

Matriz de compatibilidad

Sistemas en los que se ha probado	CentOS 7
Sistemas en los que debería funcionar	Cualquier sistema operativo que tenga instalado un servidor de Pandora FMS.

Pre-requisitos

Para poder ejecutar el plugin es necesario:

• Pandora FMS Data Server habilitado
• Pandora FMS Plugin Server habilitado
• Cuenta creada en Mist
• Apitoken creado en la API de Mist (en esta documentación se explica cómo crearlo)

Configuración

Tanto el Data Server como el Plugin Server se encuentran habilitados por defecto en una instalación de Pandora FMS. Sin embargo, es recomendable comprobar que estos servidores se encuentran habilitados, si no estamos seguros, accederemos al fichero de configuración del servidor, ubicado por defecto en /etc/pandora/pandora_server.conf

Los tokens "dataserver" y "pluginserver" deben encontrarse a 1:

dataserver 1

pluginserver 1

Dependiendo de la velocidad de conexión a internet entre el servidor de Pandora FMS y la API de Mist y el número de dispositivos dados de alta en el entorno, el plugin puede tardar más o menos tiempo en extraer la información necesaria. Para evitar timeouts, es recomendable aumentar el valor del token "plugin_timeout" también en el fichero pandora_server.conf al menos a "20":

plugin_timeout 20

Una vez se ha terminado de editar este archivo, en caso de haber sido necesario, se debe reiniciar el servicio del servidor para aplicar cambios:

/etc/init.d/pandora_server restart 

Ejecución del plugin y parámetros

El plugin necesita permisos de ejecución para poder lanzarse manualmente. En caso de que no los tenga:

chmod +x pandora_mist

La ejecución del plugin y sus parámetros son:

./pandora_mist -t <token> -o <org_id> [ -g <group> ] [ -p <prefix> ] [ --data_dir <data_dir> ]

Parameter	Description
-h	Muestra la pantalla de ayuda del plugin
-t <token>, --token <token>	Obligatorio. Token de la API de Mist
-o <org_id>, --org <org_id>	Obligatorio. Organization ID del entorno del que se extraerá la información de las zonas
-g <group>, --group <group>	Grupo al que pertenecerán los agentes creados. Por defecto: Mist
-p <prefix>, --prefix <prefix>	Prefijo en los nombres de los agentes creados. Por defecto: Mist
--data_dir <data_dir>	Directorio de lectura de ficheros de datos . Por defecto: /var/spool/pandora/data_in

Si la ejecución se ha llevado a cabo correctamente, el plugin devolverá un "1" como dato.

Cómo crear un apitoken de Mist

El apitoken es un parámetro obligatorio para autenticarse en la API de Mist y que el plugin sea capaz de extraer los datos para crear los agentes y módulos.

Crear un apitoken nuevo

Estando logado en la cuenta de Mist, abre una nueva pestaña en el mismo navegador y ve a la siguiente url para abrir la llamada a la API "Getall Create Apitoken":

https://api.eu.mist.com/api/v1/self/apitokens

(la url puede depender de tu región)

Pulsa en el botón "POST" para crear un nuevo apitoken:

Mostrar todos los apitokens creados

Para mostrar todos los apitokens creados en la cuenta, podemos usar la misma llamada que la usada para crearlos (sin presionar en el botón de POST esta vez):

https://api.eu.mist.com/api/v1/self/apitokens

Necesitaremos el valor "key" de cualquier apitoken funcionando para usarlo en nuestro plugin.

Cómo saber el "Organization ID"

El plugin extrae los datos de todas las zonas y dispositivos registrados en una Organización de Mist. Es obligatorio mandar como parámetro el valor "Organization ID" de tu cuenta de Mist. Si tu entorno tiene más de una Organización, será necesario lanzar el plugin tantas veces como Organizaciones haya.

Puedes ver el "Organization ID" estando logado en tu cuenta de Mist y navegando en el menú a Organization>Settings

En esta pantalla se puede encontrar el valor "Organization ID" justo de bajo del nombre de la Organización:

Configuración en Pandora FMS

Este plugin es un plugin de tipo servidor que se distribuye en formato pspz2, por lo tanto la integración en Pandora FMS es muy simple y se puede realizar enteramente desde la consola. En primer lugar, es necesario descargar el archivo "mist-plugin.pspz2" desde la librería de módulos de Pandora FMS. Con este archivo descargado:

Por defecto, los agentes creados por el plugin pertenecerán a un grupo llamado "Mist". Si no quieres cambiar ese grupo, el primer paso será crear este grupo "Mist". Puede realizarse en Profiles>Manage agent groups y pulsando en "Create group":

Con el grupo "Mist" creado (recuerda que ese paso es opcional), ve a Servers>Register plugin:

En esta pantalla pulsa en "Seleccionar archivo" y busca el archivo "mist-plugin.pspz2" que se ha descargado anteriormente. Después de pulsar en el botón "Upload", el plugin de servidor se creará automáticamente:

Ahora es necesario crear el módulo de plugin de servidor que lanzará el plugin de mist y actualizará los módulos creados en cada intervalo.

Ve a la vista de Módulos en el agente en el que quieras almacenar y controlar el módulo que lanzará el plugin (o crea un nuevo agente para almacenar este módulo). Puedes ir directamente a esta vista desde Resources>Manage agents y pulsando en Modules debajo del nombre del agente:

En esta vista "Módulos" selecciona el box del Type como "Create a new plugin server module" y pulsa en Create:

En esta vista de creación del módulo, selecciona:

-Name: [nombre deseado para el módulo]

-Type: Generic boolean

-Plugin: Mist Plugin

Tras seleccionar "Mist Plugin" en la caja, los campos "apitoken", "organization ID", "group", "prefix" y "data dir" serán cargados. Rellénalos con los campos que desees, pero recuerda que el "apitoken" y el "organization ID" son parámetros obligatorios para la ejecución del plugin y deben ser rellenados correctamente con la información de tu Mist API:

Tras pulsar en Create, el módulo que ejecuta el plugin se creará. Si hay algún problema con la conexión a la API de Mist o con el apitoken, el valor del módulo será "0" y pasará a estado Critical. Si todo está correctamente, el valor del módulo debe ser "1":

Módulos generados por el plugin

Si no hay ningún error de conexión, el plugin creará un agente por cada zona que haya en la cuenta de Mist que corresponda con el "Organization ID" que se le ha pasado como parámetro. Por cada uno de estos agentes:

• El alias del agente es: [prefijo pasado como parámetro]_[site_name]_[site_country_code]
• El nombre del agente es: [mismo prefijo de antes]_[site_name]_[site_country_code]_[site_id]
• El grupo del agente es el establecido como parámetro (por defecto "Mist")

Los módulos creados serán:

Nombre del módulo	Descripción
Total devices connected	Total devices connected
Total devices not connected	Total devices not in "connected" status
[device_type]_[device_name]_[device_MAC]	IP: [device_ip]. Status: [device_status]

Se creará un módulo por cada dispositivo que haya en la zona configurada en el Cloud de Mist, de tipo booleano que permanecerá en estado "OK" siempre que el estado que muestre en Mist sea "connected".

Los valores [device_type] [device_name] y [device_MAC] son extraídos directamente de los configurados en el Cloud de Mist.