joachim/mosquitto-mqtt-broker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8395c86cb8b693ca7a3c8d978e019796d8be3ff6
mosquitto-mqtt-broker/README.md

9.0 KiB
Raw Blame History

MQTT Server Setup mit Mosquitto & Web Dashboard

Komplettes MQTT Setup mit Eclipse Mosquitto Broker und MQTTUI Web Dashboard.

Features

✅ Mosquitto MQTT Broker

  • MQTT auf Port 1883
  • WebSocket auf Port 9001
  • Passwort-Authentifizierung
  • ACL (Access Control Lists)
  • Öffentliches Topic ohne Anmeldung (public/*)
  • Persistenz aktiviert

✅ Web Dashboard (MQTTUI)

  • Web-basiertes MQTT Dashboard
  • Nachrichtenverlauf mit SQLite Datenbank
  • Echtzeit-Updates
  • Läuft auf Port 5000

Verzeichnisstruktur

mqtt/
├── config/                     # Konfigurationsdateien
│   ├── mosquitto.conf          # Mosquitto Hauptkonfiguration
│   ├── acl.conf                # Access Control Lists
│   └── passwords.txt           # User/Passwort Datei (wird generiert)
├── data/                       # Mosquitto Persistenz Daten
├── log/                        # Mosquitto Log-Dateien
├── mqttui-data/                # MQTTUI Datenbank
├── docker-compose.yml          # Docker Setup
├── .env                        # Umgebungsvariablen (NICHT committen!)
├── .env.example                # Beispiel für Umgebungsvariablen
├── mqtt-panel-config.json      # Legacy Dashboard Konfiguration
├── setup.sh                    # Setup-Script für User
├── test-mqtt.sh                # Test-Script für MQTT Nachrichten
├── CLAUDE.md                   # Projekt-Dokumentation für Claude Code
└── README.md                   # Diese Datei

Quick Start

1. Umgebungsvariablen konfigurieren

# .env.example als Vorlage kopieren
cp .env.example .env

# .env editieren und sichere Passwörter setzen
nano .env

⚠️ WICHTIG: Setze sichere Passwörter in der .env Datei!

2. Server starten

# Container starten
docker compose up -d

# Logs anschauen
docker compose logs -f

3. Benutzer erstellen

# Setup-Script ausführbar machen
chmod +x setup.sh

# Alle User aus .env erstellen
./setup.sh

Das Script erstellt folgende User (Credentials aus .env):

  • admin - Vollzugriff
  • panel - Für Web Dashboard
  • testuser - Normaler User
  • device1 - IoT Device 1
  • device2 - IoT Device 2
  • monitor - Read-Only

Einzelnen User über CLI erstellen:

# Syntax: ./setup.sh create <username> <password>
./setup.sh create myuser secret123

⚠️ WICHTIG: Nach dem Erstellen eines neuen Users musst du:

  1. Die ACL-Regeln in config/acl.conf für den neuen User anpassen
  2. Mosquitto neu starten: docker compose restart mosquitto

Ohne ACL-Eintrag hat der neue User keine Zugriffsrechte!

4. Dashboard öffnen

Web Dashboard: http://localhost:5000

Zugriff

MQTT Endpoints

  • MQTT: localhost:1883
  • WebSocket: ws://localhost:9001
  • Web Dashboard: http://localhost:5000

Öffentliches Topic (ohne Anmeldung)

Topic: public/*

Beispiel mit mosquitto_pub:

# Nachricht an öffentliches Topic senden (KEINE Authentifizierung)
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "public/test" -m "Hallo Welt!"

# Öffentliches Topic abhören
docker exec mosquitto-mqtt mosquitto_sub -h localhost -t "public/#" -v

Mit Authentifizierung

Beispiel mit Admin User:

# Mit Authentifizierung publishen (Credentials aus .env verwenden)
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "devices/device1/status" -m "online" -u admin -P <ADMIN_PASSWORD>

# Mit Authentifizierung subscriben (Credentials aus .env verwenden)
docker exec mosquitto-mqtt mosquitto_sub -h localhost -t "#" -v -u admin -P <ADMIN_PASSWORD>

💡 Hinweis: Ersetze <ADMIN_PASSWORD> mit dem Passwort aus deiner .env Datei.

Benutzerverwaltung

Neuen User hinzufügen

Empfohlen - Via Setup-Script:

# Einzelnen User erstellen
./setup.sh create username password123

⚠️ Danach ACL anpassen: Bearbeite config/acl.conf und füge Regeln für den neuen User hinzu, dann:

docker compose restart mosquitto

Alternativ - Manuell:

# User hinzufügen/ändern
docker exec -it mosquitto-mqtt mosquitto_passwd -b /mosquitto/config/passwords.txt USERNAME PASSWORD

# ACL in config/acl.conf anpassen und Container neu starten
docker compose restart mosquitto

User löschen

docker exec -it mosquitto-mqtt mosquitto_passwd -D /mosquitto/config/passwords.txt USERNAME

# Container neu starten
docker compose restart mosquitto

ACL Konfiguration (acl.conf)

Die ACL definiert, wer auf welche Topics zugreifen darf:

Anonymous User (ohne Anmeldung)

user anonymous
topic read public/#
topic write public/#

Admin (alles erlaubt)

user admin
topic readwrite #

Device (nur eigene Topics)

user device1
topic write devices/device1/#
topic read devices/device1/status
topic read public/#

Nach ACL-Änderungen Container neu starten:

docker compose restart mosquitto

Dashboard

Das MQTTUI Dashboard zeigt alle MQTT Nachrichten in Echtzeit an und speichert sie in einer SQLite Datenbank.

Dashboard Konfiguration

Die Dashboard-Einstellungen werden über Umgebungsvariablen in der .env Datei konfiguriert:

  • MQTT_PANEL_USERNAME: Benutzername für den Broker-Zugriff
  • MQTT_PANEL_PASSWORD: Passwort für den Broker-Zugriff
  • SECRET_KEY: Session-Key für die Web-Oberfläche

Nach Änderungen Container neu starten:

docker compose restart mqttui

Test-Nachrichten senden

Via Docker

# Öffentlich (ohne Auth)
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "public/message" -m "Test Nachricht"

# Mit Auth (Passwort aus .env verwenden)
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "sensors/temperature" -m "22.5" -u admin -P <ADMIN_PASSWORD>
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "sensors/humidity" -m "65" -u admin -P <ADMIN_PASSWORD>
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "system/cpu" -m "45" -u admin -P <ADMIN_PASSWORD>

Oder verwende das Test-Script:

./test-mqtt.sh

Via Python (paho-mqtt)

pip install paho-mqtt

import paho.mqtt.client as mqtt
import os

# Credentials aus .env laden
admin_user = os.getenv("MQTT_ADMIN_USERNAME", "admin")
admin_pass = os.getenv("MQTT_ADMIN_PASSWORD")

client = mqtt.Client()
client.username_pw_set(admin_user, admin_pass)
client.connect("localhost", 1883)

# Nachrichten senden
client.publish("sensors/temperature", "23.4")
client.publish("sensors/humidity", "68")
client.publish("public/message", "Hallo von Python!")

client.disconnect()

Via JavaScript (Browser/Node.js)

npm install mqtt

const mqtt = require('mqtt');

// Credentials aus Umgebungsvariablen laden
const admin_user = process.env.MQTT_ADMIN_USERNAME || 'admin';
const admin_pass = process.env.MQTT_ADMIN_PASSWORD;

const client = mqtt.connect('ws://localhost:9001', {
    username: admin_user,
    password: admin_pass
});

client.on('connect', () => {
    console.log('Connected!');

    // Nachrichten senden
    client.publish('sensors/temperature', '24.1');
    client.publish('public/message', 'Hallo von Node.js!');
});

Troubleshooting

Container Logs anschauen

# Alle Logs
docker compose logs -f

# Nur Mosquitto
docker compose logs -f mosquitto

# Nur MQTTUI
docker compose logs -f mqttui

In Container einsteigen

# Mosquitto Container
docker exec -it mosquitto-mqtt sh

# MQTTUI Container
docker exec -it mqttui sh

Mosquitto Konfiguration testen

docker exec mosquitto-mqtt mosquitto -c /mosquitto/config/mosquitto.conf -v

Permissions Fehler

# Berechtigungen für passwords.txt setzen
chmod 644 passwords.txt

ACL Debug

Aktiviere Debug-Logging in mosquitto.conf:

log_type all

Dann Container neu starten und Logs prüfen.

Sicherheit für Production

⚠️ WICHTIG für Production-Umgebungen:

  1. Passwörter ändern: Alle Default-Passwörter ändern!
  2. SSL/TLS aktivieren: Verschlüsselte Verbindungen einrichten
  3. Firewall konfigurieren: Nur benötigte Ports öffnen
  4. ACL restriktiv gestalten: Principle of Least Privilege
  5. Anonymous Access prüfen: allow_anonymous false belassen
  6. Mosquitto Updates: Regelmäßig Updates einspielen

SSL/TLS einrichten (optional)

  1. Zertifikate generieren
  2. mosquitto.conf erweitern:
listener 8883
protocol mqtt
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Container verwalten

# Starten
docker compose up -d

# Stoppen
docker compose stop

# Neu starten
docker compose restart

# Stoppen und löschen
docker compose down

# Stoppen, löschen inkl. Volumes
docker compose down -v

# Nur mosquitto neu starten
docker compose restart mosquitto

Support & Dokumentation

Lizenz

Dieses Setup verwendet:

  • Eclipse Mosquitto (EPL/EDL)
  • MQTTUI (Open Source)