gilles/ipwatch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ipwatch

Browse Source
This commit is contained in:
gilles soulier
2026-02-07 16:57:37 +01:00
parent 8383104454
commit dff1b03e42
129 changed files with 19769 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

441
mqtt/docs/MQTT_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,441 @@
# 📐 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)