mqguard - MQTT traffic diagnostic tool
mqguard is tool for health monitoring and diagnostic of MQTT network. It is able to warn user about IoT device errors and provide real time diagnostic service.
Right now, mqguard is in development version only. You have to clone this repository and install it manually. Run following command from mqguard directory:
$ sudo python3 setupy.py install
Alternatively, you can install mqguard in development mode.
$ sudo pip3 install -e .
You can learn more about pip development mode.
mqguard accepts several command line options.
--config- Specify configuration file. Default
--verbose- Verbose mode.
--help- Show help message and exit.
--version- Print version.
mqguard is configured using configuration file with INI format. By default,
/etc/mqguard.conf is used. You can change this with
--config option to specify alternative path.
Configuration file syntax
Configuration file is divided into multiple sections which forms tree-like structure.
Just for future versions of mqguard. Empty section for now. Any ideas for configuration options?
Specifies group of MQTT brokers for collecting data. Mandatory section.
Enabled- List of enabled MQTT brokers. Mandatory.
Specifies group of guarded devices. Mandatory section.
Enabled- List of monitored devices. Mandatory.
Specifies group of reporters for program output. Mandatory section.
Enabled- List of enabled reporter sections. Mandatory.
Broker section describes connection to MQTT broker. By enabling this section in
[Brokers] section, mqguard will connect to this broker and start collect data.
Brokers are defined by combination of its name, host and port. Broker name must be unique.
Username- Broker username.
Password- Broker password. Mandatory if
Host- Broker listen address. Default:
Port- Broker listen port. Default:
Topic- Space separated list of topic subscriptions. Mandatory.
Device section describes guarded device. It is defined by name, which must be unique.
Name is taken from
Name option or from section name.
Name- Device name. Must be unique across all guarded devices.
Description- Device description string. It is used by some reporters.
PresenceTopic- Device presence topic.
PresenceOnline- Presence online message. Mandatory if
PresenceOffline- Presence offline message. Mandatory if
Guard- Name of device guard section. Mandatory.
TODO: Consider to add following options. It may be useful.
Latitude- Device latitude.
Longitude- Device longitude.
Elevation- Elevation of the device.
Tags- List of keywords for making device groups. Used for some advanced filtering, etc.
Guard section contains broker name and MQTT topic as key and update sections as value. There must be at least one section specified.
my-broker my/device/topic = update-section
Type- Update type. Default:
numeric- Only numeric values.
alphanumeric- Alphanumeric values.
alphabetic- Only letters.
PeriodMax- Maximum update period. Check if device simply stopped sending data for some reason.
PeriodMin- Minimum update period. Protect network from message flooding.
ErrorCodes- List of update error codes.
ValidRangeMin- Minimum update value. Numeric type only.
ValidRangeMax- Maximum update value. Numeric type only.
Reporter is object for program output. Its responsibility is notify user about device problems, or provide real time diagnostic information.
Type- Reporter type.
socket- TCP/IP socket reporter.
websocket- Websocket reporter.
logging- Logging errors into plain log file or to standard output. Not implemented yet.
database- Log errors into database. Not implemented yet.
sms- SMS notification. Not implemented yet.
trigger- Execute shell script. Not implemented yet.
- Add specification which devices should be reported. It is nonsense to send SMS for all devices, while user is interested only about few ones. This mechanism should be implemented as some kind of report domain.
ListenAddress- Websocket listen address. Default:
ListenPort- Websocket listen port. Default:
OutputFormat- Preffered websocket output format. Default:
json- JSON format.
xml- XML format.
plain- Plain text format. Similar to
loggingreporter type, except logs are send over websocket channel.
File- Absolute path to log file.
- Rotating logs.
- Log formatting.
If you like this project, you can contribute. Of course :)