# Mist Plugin

# Introduction

Ver. 130721  
This plug-in is used to monitor devices registered in Mist Cloud.  
It connects to the Mist cloud service to get data about registered zones and devices and sends this data to the Pandora FMS server from which it has been executed.  
Type: Server plug-in

# Compatibility Matrix

<table border="1" id="bkmrk-systems-tested-cento" style="border-collapse: collapse; width: 100%; height: 58px;"><tbody><tr style="height: 29px;"><td style="width: 42.0987%; height: 29px;">**Systems tested**</td><td style="width: 57.9013%; height: 29px;">CentOS 7</td></tr><tr style="height: 29px;"><td style="width: 42.0987%; height: 29px;">**Systems where it should work**</td><td style="width: 57.9013%;">Any Linux operating system that has a Pandora FMS server installed.

</td></tr></tbody></table>

# Prerequisites

To be able to execute this plug-in it's necessary:

- Pandora FMS Data Server enabled.
- Pandora FMS Plugin Server enabled.
- Account created in Mist
- APItoken created in Mist API (this documentation explains how to create it)

# Configuration

Both the Data Server and the Plugin Server are enabled by default in Pandora FMS. However, if we would like to check that we have both servers enabled, or we are not sure, we can access to the Pandora FMS server configuration file, located in */etc/pandora/pandora\_server.conf*.

`dataserver 1`

`pluginserver 1`

Depending on the speed of the internet connection of the Pandora Server with the Mist API and the number of devices in your environment, the plugin can take more or less time to extract the necessary information. To avoid unnecessary timeouts, it is advisable to increase the value of the "plugin\_timeout" token also in */etc/pandora/pandora\_server.conf* file to at least "20":

`plugin_timeout 20`

Once we've finished editing this file, we must restart the server service:

`/etc/init.d/pandora_server restart`

# Plugin execution and parameters

The plugin needs execution permissions to be launched:

`chmod +x pandora_mist`

The execution and the parameters of the plugin are:

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

<table border="1" id="bkmrk-parameter-descriptio" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 26.7902%;">**Parameter**</td><td style="width: 73.2098%;">**Description**</td></tr><tr><td style="width: 26.7902%;">-h</td><td style="width: 73.2098%;">Shows plugin help screen</td></tr><tr><td style="width: 26.7902%;">-t &lt;token&gt;, --token &lt;token&gt;</td><td style="width: 73.2098%;">**Mandatory**. Mist API token</td></tr><tr><td style="width: 26.7902%;">-o &lt;org\_id&gt;, --org &lt;org\_id&gt;</td><td style="width: 73.2098%;">**Mandatory.** Mist organization ID from which to extract the information of the zones</td></tr><tr><td style="width: 26.7902%;">-g &lt;group&gt;, --group &lt;group&gt;

</td><td style="width: 73.2098%;">Group where agents created will belong. *Default: Mist*</td></tr><tr><td style="width: 26.7902%;">-p &lt;prefix&gt;, --prefix &lt;prefix&gt;</td><td style="width: 73.2098%;">Prefix in the created agent names. *Default: Mist*</td></tr><tr><td style="width: 26.7902%;">--data\_dir &lt;data\_dir&gt;</td><td style="width: 73.2098%;">Pandora FMS data directory. *Default: /var/spool/pandora/data\_in*</td></tr></tbody></table>

If the execution was successful we should see '1' data when running the plugin.

# How to create Mist apitoken

APItoken is a mandatory parameter to authenticate in Mist API and that the plugin is able to extract the data to create the modules and agents.

#### Create a new apitoken

Being logged in your Mist account, open a new tab in the same browser and go to this url to launch "Getall Create Apitoken":

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

(url may depend of your region)

Press on "POST" button to create a new apitoken:

[![getapitoken.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/getapitoken.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/getapitoken.png)

#### Show all apitoken created

To show all apitokens created, we can use the sale API call as we used to create them:

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

We will need "key" value of any working apitoken to use in our plugin.

# How to know the "Organization ID"

The plugin extracts the data of all sites and devices registered in a Mist Organization. It is mandatory to send as parameter the "organization ID" of your Mist API account. If your environment has more than one Organization, it is necessary to launch the plugin one time for each of those organizations.

You can see your organization ID being logged in your Mist account and going to Organization&gt;Settings:

[![orgid1.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/orgid1.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/orgid1.png)

On this screen you can find and copy the "Organization ID" just bellow "Organization Name":

[![orgid2.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/orgid2.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/orgid2.png)

# Configuration in Pandora FMS

This is a server plugin distributed in pspz2 format, so the integration in Pandora FMS is very easy and can be done entirely from the console. It is necessary to download the file "mist-plugin.pspz2" from Pandora FMS library. With this file downloaded:

As default, the agents created by the plugin will be stored in a Group named "Mist". If you don't want to change that group, the first step is to create "Mist" group. It can be done in *Profiles&gt;Manage agent groups* and clicking on "Create group":

[![mist7.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist7.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist7.png)

With the "Mist" group created (remember that it is optional), go to *Servers&gt;Register plugin*:

[![mist1.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist1.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist1.png)

In this screen press on "Select file" and look for "mist-plugin.pspz2" file. After pressing on "Upload" button the server plugin must be created:

[![mist2.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist2.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist2.png)

Now it is necessary to create the server plugin module that will launch the mist plugin and update the modules created by it in each time interval.

Go to modules view in the agent where you want to store and control this plugin launch module (or create a new agent to store the module). You can go directly to that view in *Resources&gt;Manage agents* and Modules bellow the agent name:

[![mist3.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist3.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist3.png)

On this Modules view select the Type "Create a new plugin server module" and press on Create:

[![mist4.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist4.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist4.png)

On this Module creation view select:

-Name: \[name desired for module plugin\]

-Type: Generic boolean

-Plugin: Mist Plugin

After selecting "Mist Plugin" in the box, the fields "apitoken", "organization ID", "group", "prefix" and "data dir" will be loaded. Fill them with the data that you want, but remember "apitoken" and "organization ID" are mandatory for plugin execution and must be filled with the correct data of your Mist API:

[![mist5.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist5.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist5.png)

After pressing on Create, the module that will launch the mist plugin will be created. If there is any problem with Mist connection or with the token, the value of the module will be "0" and will go to Critical. If everything is fine, the module value must be "1":

[![mist6.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist6.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist6.png)

# Modules generated by the plugin

If there is no connection error, the plugin will create an agent for each zone created in the Mist account that matches the org\_id passed as parameter. For each one of those agents:

- The agent alias is: \[prefix configured as parameter\]\_\[site\_name\]\_\[site\_country\_code\]
- The agent name is: \[same prefix as before\]\_\[site\_name\]\_\[site\_country\_code\]\_\[site\_id\]
- The agent group is the configured as parameter (default "Mist")

Modules created will be:

<table border="1" id="bkmrk-module-name-descript" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 50%;">**Module name**</td><td style="width: 50%;">**Description**</td></tr><tr><td style="width: 50%;">Total devices connected</td><td style="width: 50%;">Total devices connected</td></tr><tr><td style="width: 50%;">Total devices not connected</td><td style="width: 50%;">Total devices not in "connected" status</td></tr><tr><td style="width: 50%;">\[device\_type\]\_\[device\_name\]\_\[device\_MAC\]</td><td style="width: 50%;">IP: \[device\_ip\]. Status: \[device\_status\]</td></tr></tbody></table>

A module will be created for each device that has each zone configured in the Mist Cloud, of boolean type and will be in "OK" status whenever its status is "connected".

The \[device\_type\], \[device\_name\] and \[device\_MAC\] values are extracted directly from the Mist Cloud.

[![mist8.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist8.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist8.png)

[![mist10.png](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/scaled-1680-/mist10.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2021-07/mist10.png)