# IOT Discovery
# Introduction
**The purpose of the Pandora IOT integration** is to monitor messages received from an mqtt broker server.
For this, the integration makes use of an MQTT broker server, which opens the possibility of subscribing to a topic to receive messages and a Discovery plugin, which allows configuring a filtering of these messages and visualizing the post-processing of these messages in the PandoraFMS console through agents and modules that are sent via XML to the Pandora server.
The monitoring of IoT (Internet of Things) devices allows to supervise in real time the status of connected equipment and sensors, facilitating fast and effective decision making. By integrating these devices into monitoring systems, companies can detect problems in advance, optimize their operations and reduce downtime.
**Why is it useful to monitor IoT devices?**
Imagine you have temperature sensors in an industrial plant and the MQTT server receives messages with temperature values every minute, the integration can filter those values that are out of the acceptable range (e.g. > 80°C) and generate an alert module in PandoraFMS, which can help prevent problems and protect against possible incidents.
[](https://pandorafms.com/guides/public/uploads/images/gallery/2025-03/DG6diagrama-other.png)
# Pre requisites
- Connectivity to the MQTT server
- Connectivity to the database receiving the messages
# Parameters
**Parameters**
--conf
Path to configuration file
--filter\_conf
Path to message filter archive
--verbosity
Used to activate debug mode
**Conf file (--conf)**
```
db_path = Path to sql database lite
threads = < Maximum number of threads used >
timestamp_filter = < Timestamp in seconds from which the messages will be filtered >
agents_group_name = < Group name for the created agents >
interval = < Interval in seconds for the agents >
tentacle_ip = < IP of the target machine for the created agents >
tentacle_port = < Tentacle port, default : 41121 >
```
**Example**
```
db_path = /var/spool/pandora/data_in/discovery/pandorafms.iot/mqtt_messages.db
threads = 4
timestamp_filter = 1738000000
agents_group_name = Unknown
interval = 300
tentacle_ip = 127.0.0.1
tentacle_port = 41121
```
**File to filter messages (--filter\_conf)**
```
#=======================================================================
# Filter Configuration
#=======================================================================
filter_begin: < Marks the beginning of a filter configuration. Everything until filter_end belongs to the same filter. Mandatory. >
filter_module_name: < Name assigned to the module that generates the filter. Mandatory. >
filter_module_type: < Type of module that generates the filter. Mandatory. >
filter_topic: < Regular expression or exact text that must match the message topic for the filter to apply. Optional. By default, it matches any topic. >
filter_topic_exact_match: < Defines whether filter_topic is treated as a regular expression (0) or exact text (1). Optional. Default is 0. >
filter_message: < Regular expression or exact text that must match the message content for the filter to apply. Optional. By default, it matches any message. >
filter_message_exact_match: < Defines whether filter_message is treated as a regular expression (0) or exact text (1). Optional. Default is 0. >
filter_message_capture_regex: < Regular expression with capture groups to extract values from the message. >
< Captured values will be stored in macros '__regexN__', where N is the capture group index. >
filter_message_capture_json: < List of JSON paths (separated by '|') to extract values, using the same format as jq. >
< Captured values will be stored in macros '__jsonN__', where N is the path index. >
filter_module_value: < Value assigned to the module that generates the filter. Mandatory. >
filter_end: < Marks the end of a filter configuration. Everything from filter_begin belongs to the same filter. Mandatory. >
# Available macros for use in filter_module_name and filter_module_value:
__topic__: < Replaced with the exact topic of the processed message. >
__regexN__: < Replaced with the corresponding value captured by filter_message_capture_regex. >
__jsonN__: < Replaced with the corresponding value captured by filter_message_capture_json. >
```
**Example**
```
filter_begin
filter_module_name pressure
filter_module_type generic_data_string
filter_topic sensor/humidity
filter_topic_exact_match 1
filter_message Value:
filter_message_exact_match 1
filter_message_capture_regex (\b\w{6}\b).*?(\b\w{7}\b).*?(\d{3})\s(\w)-
filter_message_capture_json
filter_module_value 1__regex1__ __regex2__ __topic__
filter_end
filter_begin
filter_module_name humidity
filter_module_type generic_data_string
filter_topic sensor/pressure
filter_topic_exact_match 1
filter_message
filter_message_exact_match 1
filter_message_capture_regex
filter_message_capture_json $.extra_info[0].value|$.extra_info[1].value
filter_module_value 2 __json1__ __json2__
filter_end
```
# Manual execution
The format of the plugin execution is as follows:
```
./proccess_messages --conf < path to configuration file > --filter_conf < path to file with message filters >
```
For example:
```
./proccess_messages --conf /var/spool/pandora/data_in/discovery/pandorafms.iot/file.conf --filter_conf /var/spool/pandora/data_in/discovery/pandorafms.iot/file_filters.conf
```
The execution will return an output in JSON format with information about the execution, and will generate an XML file for each agent (topic) and each message that has passed the filters, which will be sent to the Pandora FMS server by the transfer method indicated in the configuration.
For example:
{"summary": {"Total agents": 2, "Total messages": 141}}
```
{"summary": {"Total agents": 2, "Total messages": 2}}
```
# Discovery
This plugin can be integrated with Pandora FMS Discovery.
To do so, you must load the “.disco” package that you can download from the Pandora FMS library:
[https://pandorafms.com/library/](https://pandorafms.com/library/)
[](https://pandorafms.com/guides/public/uploads/images/gallery/2025-02/image.png)
Once loaded, you will be able to receive and monitor messages from a broker, creating Discovery tasks from the Management > Discovery > App section.
The following minimum data will be requested for each task:
- **DB path**: Database file path
- **Timestamp**: Timestamp in seconds from which it will be filtered.
- **Tentacle IP:** IP of the Tentacle server to which the agents' data will be sent. Normally this parameter will not be modified.
- **Tentacle port**: Tentacle server port to send the data to. Normally this parameter will not be modified.
- **Tentacle extra options:** Tentacle extra options.
[](https://pandorafms.com/guides/public/uploads/images/gallery/2025-02/tjkimage.png)
Filter settings can also be adjusted to customize the desired monitoring:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2025-02/nWDimage.png)
- **Max threads:** Number of wires to be used.
- **FIlter message modules**: Filter configuration options for the modules. More details on the possible options and labels to be used in this section can be found in the “parameters” section of this manual.
Successfully completed tasks will have an execution summary with the following information:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2025-02/WI4image.png)
- **Total agents** : Total number of agents generated by the task.
- **Total messages:** Total number of messages that have passed the filters.
# Agents and modules generated by the plugin
- An agent will be created for each topic containing messages that have passed the filters.
- A module will be created for each message that has passed the filters.