mqttman - Mosquitto Manager

A simple web-based management interface for the Mosquitto MQTT broker with real-time monitoring, data logging, and user management.

Features

• Web-Based Management Interface - Easy-to-use dashboard for managing your Mosquitto broker
• User & Group Management - Create users and groups with granular ACL (Access Control List) permissions
• Real-Time Monitoring - Live MQTT message monitoring with WebSocket support
• Data Logging - Multi-resolution time-series data storage in SQLite
  • Raw data (1-second resolution, 15 minutes retention)
  • 1-minute intervals (6 hours retention)
  • 5-minute intervals (1 day retention)
  • 15-minute intervals (1 week retention)
  • 1-hour intervals (1 month retention)
  • 6-hour intervals (6 months retention)
  • 1-day intervals (10 years retention)
• Data Channels - Monitor specific MQTT topics with customizable data extraction
  • Support for numeric data, JSON path extraction, and on/off states
  • Data validation with min/max thresholds
• Charting & Visualization - Built-in charts for historical data analysis
• Import/Export - Backup and restore your configuration
• Secure by Default - Auto-generated passwords, localhost-first security model

Requirements

• Python 3.7+
• Mosquitto MQTT Broker (version 2.0.21 or higher recommended)
• Required Python packages (see Installation)

Installation

1. Clone the repository

   git clone https://github.com/Pieter86/MQTTmanager.git
   cd MQTTmanager

2. Install Python dependencies

   pip install fastapi uvicorn paho-mqtt psutil

3. Download Mosquitto

   • Windows: Download from mosquitto.org/download
   • Linux: sudo apt-get install mosquitto (or equivalent)
   • macOS: brew install mosquitto

   Place the mosquitto executable in the same directory as mqttman.py

Quick Start

1. Run mqttman

   python mqttman.py

2. Access the web interface

   Open your browser to: http://localhost:8088

3. First-time setup

   • The monitor user password is auto-generated and stored in .monitor_password
   • Create your first MQTT user via the web interface
   • Configure data channels to start monitoring topics

Command Line Options

python mqttman.py [options]

Options:
  --port, -p PORT          Web server port (default: 8088)
  --host HOST              Host to bind to (default: 0.0.0.0)
  --mqtt-port PORT         MQTT broker port (default: 1883)
  --skip-version-check     Skip Mosquitto version validation

Usage Examples

Starting on a custom port

python mqttman.py --port 9000

Localhost only (more secure)

python mqttman.py --host 127.0.0.1

Custom MQTT port

python mqttman.py --mqtt-port 1884

Security

• Local Access: Connections from 127.0.0.1 are always allowed without authentication
• Remote Access: Requires HTTP Basic authentication (configurable via settings)
• CORS: Restricted to localhost origins only
• Password Storage: Uses PBKDF2-SHA512 hashing for MQTT user passwords
• Auto-generated Credentials: Monitor user password is cryptographically secure

Configuration

All configuration is stored in the working directory:

• mosquitto.conf - Mosquitto broker configuration
• passwd - MQTT user passwords (hashed)
• acl - Access control list
• users.json - User metadata
• groups.json - Group definitions
• manager_settings.json - Web UI settings
• data_logger.db - SQLite database for logged data
• .monitor_password - Auto-generated monitor password (keep secure!)

Data Channels

Create data channels to extract and log specific data from MQTT topics:

1. Numeric Data: Extract numeric values from messages
2. JSON Path: Extract values from JSON payloads using path notation
3. On/Off States: Monitor boolean states (1/0, true/false, on/off)

Channels support validation with min/max thresholds and include historical data visualization.

API Endpoints

The web interface provides a REST API:

• GET / - Main dashboard
• POST /users - Create MQTT user
• PUT /users/{username} - Update user
• DELETE /users/{username} - Delete user
• POST /groups - Create group
• POST /channels - Create data channel
• GET /channels/{name}/data - Get channel data
• POST /service/start - Start Mosquitto
• POST /service/stop - Stop Mosquitto
• GET /export - Export configuration
• POST /import - Import configuration

Development

Built with:

• FastAPI - Modern web framework
• Paho MQTT - MQTT client library
• SQLite - Time-series data storage
• WebSockets - Real-time updates
• ECharts - Data visualization

Troubleshooting

Mosquitto not starting?

• Check that mosquitto.exe (Windows) or mosquitto (Linux/Mac) is in the same directory
• Verify version is 2.0.21+ with mosquitto --help
• Check logs in the web interface

Can't access remotely?

• Set a web password in Settings
• Ensure --host 0.0.0.0 is used (default)
• Check firewall settings

Data not logging?

• Verify the data channel topic pattern matches your MQTT messages
• Check the data type matches your payload format
• Use the debug view to see raw messages

Report issues on GitHub: Issues can be reported via the GitHub repository

Version

Current version: 0.1.65