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.
Install
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.
Options
mqguard accepts several command line options.
-c
,--config
- Specify configuration file. Default/etc/mqguard.conf
.-v
,--verbose
- Verbose mode.-h
,--help
- Show help message and exit.--version
- Print version.
Configuration
mqguard is configured using configuration file with INI format. By default, /etc/mqguard.conf
is used. You can change this with -c
or --config
option to specify alternative path.
Configuration file syntax
Configuration file is divided into multiple sections which forms tree-like structure.
[Global]
section
Just for future versions of mqguard. Empty section for now. Any ideas for configuration options?
[Brokers]
section
Specifies group of MQTT brokers for collecting data. Mandatory section.
Enabled
- List of enabled MQTT brokers. Mandatory.
[Devices]
section
Specifies group of guarded devices. Mandatory section.
Enabled
- List of monitored devices. Mandatory.
[Reporters]
section
Specifies group of reporters for program output. Mandatory section.
Enabled
- List of enabled reporter sections. Mandatory.
Broker section
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 ifUsername
is defined.Host
- Broker listen address. Default:localhost
Port
- Broker listen port. Default:1883
Topic
- Space separated list of topic subscriptions. Mandatory.
Device section
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 ifPresenceTopic
is definedPresenceOffline
- Presence offline message. Mandatory ifPresenceTopic
is definedGuard
- 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
Guard section contains broker name and MQTT topic as key and update sections as value. There must be at least one section specified.
Example: my-broker my/device/topic = update-section
Update section
Type
- Update type. Default:alphanumeric
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 section
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.mail
- Notify error via e-mail. Not implemented yet.sms
- SMS notification. Not implemented yet.trigger
- Execute shell script. Not implemented yet.
TODO:
- 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.
socket
and websocket
reporter
Options for ListenAddress
- Websocket listen address. Default:0.0.0.0
ListenPort
- Websocket listen port. Default:80
OutputFormat
- Preffered websocket output format. Default:json
json
- JSON format.xml
- XML format.plain
- Plain text format. Similar tologging
reporter type, except logs are send over websocket channel.
logging
reporter
Options for File
- Absolute path to log file.
TODO:
- Rotating logs.
- Log formatting.
mail
reporter
Options for - TODO
Contributing
If you like this project, you can contribute. Of course :)