442 lines
14 KiB
Markdown
442 lines
14 KiB
Markdown
# 📐 Architecture MQTT pour IPWatch
|
|
|
|
## 1. Vue d'ensemble
|
|
|
|
L'architecture MQTT d'IPWatch implémente un système de contrôle à distance des équipements réseau basé sur le protocole MQTT (Message Queuing Telemetry Transport).
|
|
|
|
### 1.1 Objectifs
|
|
|
|
- **Contrôle centralisé** : Gérer shutdown/reboot depuis l'interface IPWatch
|
|
- **Légèreté** : Protocol MQTT léger et performant
|
|
- **Fiabilité** : QoS MQTT pour garantir la livraison des messages
|
|
- **Scalabilité** : Support de centaines d'équipements simultanément
|
|
- **Intégration** : Compatible Home Assistant et autres systèmes domotiques
|
|
|
|
### 1.2 Composants
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ IPWatch Ecosystem │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌───────────────┐ ┌──────────────┐ │
|
|
│ │ Web Interface │────────►│ Backend │ │
|
|
│ │ (Vue.js) │ HTTP │ (FastAPI) │ │
|
|
│ └───────────────┘ API └──────┬───────┘ │
|
|
│ │ │
|
|
│ paho-mqtt (publish) │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ MQTT Broker (Mosquitto) │ │
|
|
│ │ │ │
|
|
│ │ Topics: │ │
|
|
│ │ • ipwatch/device/{IP}/command │ │
|
|
│ │ • ipwatch/device/{IP}/status │ │
|
|
│ │ • ipwatch/device/{IP}/availability │ │
|
|
│ └─────────────────┬───────────────────────────────┘ │
|
|
│ │ MQTT (subscribe) │
|
|
│ │ │
|
|
│ ┌──────────┼──────────┬──────────┬──────────┐ │
|
|
│ ▼ ▼ ▼ ▼ ▼ │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ ... │ │ Agent N │ │
|
|
│ │ 10.0.0.1│ │ 10.0.0.2│ │ 10.0.0.3│ │ │ │ 10.0.0.N│ │
|
|
│ │ │ │ │ │ │ │ │ │ │ │
|
|
│ │ Python │ │ Python │ │ Python │ │ Python │ │ Python │ │
|
|
│ │ systemd │ │ systemd │ │ systemd │ │ systemd │ │ systemd │ │
|
|
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 2. Topics MQTT
|
|
|
|
### 2.1 Hiérarchie des Topics
|
|
|
|
```
|
|
ipwatch/
|
|
└── device/
|
|
└── {IP_ADDRESS}/
|
|
├── command # Commandes envoyées par IPWatch
|
|
├── status # Statut publié par l'agent
|
|
├── availability # Disponibilité de l'agent (online/offline)
|
|
└── response # Réponses/acquittements de l'agent
|
|
```
|
|
|
|
### 2.2 Détail des Topics
|
|
|
|
#### `ipwatch/device/{IP}/command`
|
|
- **Direction** : IPWatch Backend → Agent
|
|
- **QoS** : 1 (at least once)
|
|
- **Retain** : false
|
|
- **Payload** : JSON
|
|
- **Commandes supportées** :
|
|
- `shutdown` : Arrêt de la machine
|
|
- `reboot` : Redémarrage de la machine
|
|
- `status` : Demande de statut
|
|
|
|
**Exemple** :
|
|
```json
|
|
{
|
|
"command": "shutdown",
|
|
"timestamp": "2025-12-23T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
#### `ipwatch/device/{IP}/status`
|
|
- **Direction** : Agent → IPWatch Backend
|
|
- **QoS** : 1
|
|
- **Retain** : false
|
|
- **Payload** : JSON avec métriques système
|
|
|
|
**Exemple** :
|
|
```json
|
|
{
|
|
"hostname": "server-01",
|
|
"ip": "10.0.0.100",
|
|
"platform": "Linux",
|
|
"platform_version": "5.15.0-91-generic",
|
|
"uptime": 86400,
|
|
"cpu_percent": 45.2,
|
|
"memory_percent": 62.5,
|
|
"disk_percent": 78.3,
|
|
"timestamp": "2025-12-23T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
#### `ipwatch/device/{IP}/availability`
|
|
- **Direction** : Agent → Tous
|
|
- **QoS** : 1
|
|
- **Retain** : true (important!)
|
|
- **Payload** : Texte simple
|
|
- **Valeurs** : `online` | `offline`
|
|
|
|
#### `ipwatch/device/{IP}/response`
|
|
- **Direction** : Agent → IPWatch Backend
|
|
- **QoS** : 1
|
|
- **Retain** : false
|
|
- **Payload** : JSON avec résultat de la commande
|
|
|
|
**Exemple** :
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Shutdown en cours...",
|
|
"timestamp": "2025-12-23T10:30:05Z"
|
|
}
|
|
```
|
|
|
|
## 3. Flux de Communication
|
|
|
|
### 3.1 Shutdown/Reboot
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant UI as IPWatch UI
|
|
participant BE as Backend
|
|
participant BR as MQTT Broker
|
|
participant AG as Agent (10.0.0.100)
|
|
|
|
UI->>BE: POST /api/tracking/shutdown/10.0.0.100
|
|
BE->>BR: PUBLISH ipwatch/device/10.0.0.100/command
|
|
Note over BR: QoS 1
|
|
BR->>AG: {"command": "shutdown"}
|
|
AG->>BR: PUBLISH ipwatch/device/10.0.0.100/response
|
|
Note over AG: {"success": true, "message": "Shutdown en cours..."}
|
|
AG->>BR: PUBLISH ipwatch/device/10.0.0.100/availability
|
|
Note over AG: "offline"
|
|
AG->>AG: sudo shutdown -h now
|
|
BE-->>UI: 200 OK {"message": "Commande envoyée"}
|
|
```
|
|
|
|
### 3.2 Wake-on-LAN
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant UI as IPWatch UI
|
|
participant BE as Backend
|
|
participant AG as Agent (offline)
|
|
|
|
UI->>BE: POST /api/tracking/wol/10.0.0.100
|
|
BE->>BE: send_magic_packet(MAC)
|
|
Note over BE: Broadcast UDP
|
|
BE-->>UI: 200 OK
|
|
Note over AG: Machine démarre
|
|
AG->>AG: Agent systemd démarre
|
|
AG->>BR: CONNECT
|
|
AG->>BR: PUBLISH availability "online"
|
|
AG->>BR: PUBLISH status {...}
|
|
```
|
|
|
|
### 3.3 Monitoring périodique
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant AG as Agent
|
|
participant BR as MQTT Broker
|
|
participant HA as Home Assistant
|
|
|
|
loop Chaque 30 secondes
|
|
AG->>BR: PUBLISH ipwatch/device/10.0.0.100/status
|
|
Note over AG: CPU, RAM, Disk, Uptime
|
|
BR->>HA: Forward status
|
|
Note over HA: Update sensors
|
|
end
|
|
```
|
|
|
|
## 4. Gestion des Erreurs
|
|
|
|
### 4.1 Agent déconnecté
|
|
|
|
**Problème** : L'agent perd la connexion MQTT
|
|
|
|
**Solution** :
|
|
- **Last Will Testament** : Message `offline` publié automatiquement sur `availability`
|
|
- **Reconnexion automatique** : L'agent tente de se reconnecter (retry avec backoff)
|
|
- **QoS 1** : Garantit la livraison du message d'offline
|
|
|
|
### 4.2 Commande non livrée
|
|
|
|
**Problème** : La commande n'atteint pas l'agent
|
|
|
|
**Solution** :
|
|
- **QoS 1** : Le broker MQTT garantit au moins une livraison
|
|
- **Timeout** : Le backend attend 5 secondes puis retourne une erreur
|
|
- **Retry** : L'utilisateur peut retenter l'opération
|
|
|
|
### 4.3 Agent en erreur
|
|
|
|
**Problème** : L'agent reçoit la commande mais ne peut l'exécuter
|
|
|
|
**Solution** :
|
|
- **Message de réponse** : L'agent publie sur `response` avec `success: false`
|
|
- **Logging** : Logs détaillés dans journalctl
|
|
- **Notification** : L'UI affiche l'erreur à l'utilisateur
|
|
|
|
## 5. Sécurité
|
|
|
|
### 5.1 Authentification
|
|
|
|
```
|
|
┌──────────────────────┐
|
|
│ MQTT Broker │
|
|
│ (Mosquitto) │
|
|
│ │
|
|
│ password_file: │
|
|
│ /etc/mosquitto/passwd│
|
|
│ │
|
|
│ Users: │
|
|
│ • ipwatch (backend) │
|
|
│ • agent (clients) │
|
|
└──────────────────────┘
|
|
```
|
|
|
|
**Configuration** :
|
|
```bash
|
|
# Créer les utilisateurs
|
|
mosquitto_passwd -c /etc/mosquitto/passwd ipwatch
|
|
mosquitto_passwd /etc/mosquitto/passwd agent
|
|
|
|
# Dans mosquitto.conf
|
|
allow_anonymous false
|
|
password_file /etc/mosquitto/passwd
|
|
```
|
|
|
|
### 5.2 Chiffrement TLS/SSL
|
|
|
|
```
|
|
listener 8883
|
|
cafile /etc/mosquitto/ca.crt
|
|
certfile /etc/mosquitto/server.crt
|
|
keyfile /etc/mosquitto/server.key
|
|
require_certificate false
|
|
```
|
|
|
|
### 5.3 ACL (Access Control List)
|
|
|
|
```
|
|
# /etc/mosquitto/acl
|
|
# Backend peut publier sur command
|
|
user ipwatch
|
|
topic write ipwatch/device/+/command
|
|
|
|
# Agents peuvent publier sur status/response/availability
|
|
user agent
|
|
topic write ipwatch/device/+/status
|
|
topic write ipwatch/device/+/response
|
|
topic write ipwatch/device/+/availability
|
|
topic read ipwatch/device/+/command
|
|
```
|
|
|
|
## 6. Performance et Scalabilité
|
|
|
|
### 6.1 Dimensionnement
|
|
|
|
| Métrique | Valeur | Notes |
|
|
|----------|--------|-------|
|
|
| Agents max | 500 | Limité par le broker |
|
|
| Messages/sec | 1000 | Dépend du hardware |
|
|
| Latence | <100ms | Sur réseau local |
|
|
| Bande passante | ~10 KB/s par agent | Pour statut 30s |
|
|
|
|
### 6.2 Optimisations
|
|
|
|
**Payload compression** :
|
|
- JSON minifié (pas d'indentation)
|
|
- Champs courts
|
|
- Pas de données redondantes
|
|
|
|
**Keep-alive** :
|
|
- 60 secondes (défaut)
|
|
- Réduit le trafic réseau
|
|
|
|
**QoS adaptatif** :
|
|
- QoS 1 pour commandes critiques
|
|
- QoS 0 pour statut non-critique
|
|
|
|
## 7. Compatibilité Home Assistant
|
|
|
|
### 7.1 MQTT Discovery
|
|
|
|
L'agent publie automatiquement sa configuration pour Home Assistant :
|
|
|
|
```json
|
|
{
|
|
"name": "Server 01",
|
|
"unique_id": "ipwatch_10_0_0_100",
|
|
"state_topic": "ipwatch/device/10.0.0.100/status",
|
|
"availability_topic": "ipwatch/device/10.0.0.100/availability",
|
|
"json_attributes_topic": "ipwatch/device/10.0.0.100/status",
|
|
"device": {
|
|
"identifiers": ["ipwatch_10_0_0_100"],
|
|
"name": "Server 01",
|
|
"model": "IPWatch MQTT Agent",
|
|
"manufacturer": "IPWatch"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Topic Discovery** :
|
|
```
|
|
homeassistant/sensor/ipwatch_10_0_0_100/config
|
|
```
|
|
|
|
### 7.2 Entités créées
|
|
|
|
Home Assistant crée automatiquement :
|
|
- **Sensor** : CPU, RAM, Disk, Uptime
|
|
- **Binary Sensor** : Availability (online/offline)
|
|
- **Button** : Shutdown, Reboot
|
|
|
|
## 8. Monitoring et Logs
|
|
|
|
### 8.1 Logs Agent
|
|
|
|
```bash
|
|
# Logs en temps réel
|
|
sudo journalctl -u ipwatch-mqtt-agent -f
|
|
|
|
# Logs des dernières 24h
|
|
sudo journalctl -u ipwatch-mqtt-agent --since "24 hours ago"
|
|
|
|
# Recherche d'erreurs
|
|
sudo journalctl -u ipwatch-mqtt-agent -p err
|
|
```
|
|
|
|
### 8.2 Logs Broker
|
|
|
|
```bash
|
|
# Logs Mosquitto
|
|
sudo journalctl -u mosquitto -f
|
|
|
|
# Activer le debug dans mosquitto.conf
|
|
log_type all
|
|
log_dest /var/log/mosquitto/mosquitto.log
|
|
```
|
|
|
|
### 8.3 Métriques
|
|
|
|
**Collecte via MQTT** :
|
|
- Nombre de clients connectés
|
|
- Messages publiés/reçus
|
|
- Latence des messages
|
|
|
|
**Grafana + Prometheus** (optionnel) :
|
|
- Dashboard pour visualiser les métriques
|
|
- Alertes sur déconnexions
|
|
|
|
## 9. Diagrammes Détaillés
|
|
|
|
### 9.1 État de l'Agent
|
|
|
|
```
|
|
┌─────────┐
|
|
│ Start │
|
|
└────┬────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Load Config │
|
|
└────┬────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Connect MQTT │──┐
|
|
│ Broker │ │
|
|
└────┬────────────┘ │
|
|
│ │ Retry
|
|
│ Success │ on error
|
|
▼ │
|
|
┌─────────────────┐ │
|
|
│ Subscribe to │ │
|
|
│ command topic │ │
|
|
└────┬────────────┘ │
|
|
│ │
|
|
▼ │
|
|
┌─────────────────┐ │
|
|
│ Publish │◄─┘
|
|
│ availability │
|
|
│ "online" │
|
|
└────┬────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Main Loop │
|
|
│ • Listen MQTT │
|
|
│ • Publish status│
|
|
│ every 30s │
|
|
└────┬────────────┘
|
|
│
|
|
│ Receive shutdown
|
|
▼
|
|
┌─────────────────┐
|
|
│ Publish │
|
|
│ "offline" │
|
|
└────┬────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Execute │
|
|
│ shutdown │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## 10. Références
|
|
|
|
- **MQTT v3.1.1 Specification** : http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
|
|
- **Mosquitto Documentation** : https://mosquitto.org/documentation/
|
|
- **Paho MQTT Python** : https://github.com/eclipse/paho.mqtt.python
|
|
- **Home Assistant MQTT Discovery** : https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery
|
|
|
|
## 11. TODO / Améliorations Futures
|
|
|
|
- [ ] Support SSL/TLS par défaut
|
|
- [ ] Compression des payloads (gzip)
|
|
- [ ] Authentification par certificat client
|
|
- [ ] Métriques Prometheus
|
|
- [ ] Dashboard Grafana
|
|
- [ ] Support MQTT v5
|
|
- [ ] Broadcast pour commandes multi-équipements
|
|
- [ ] Planification de shutdown/reboot (cron-like)
|