Files

gilles dff1b03e42 ipwatch

2026-02-07 16:57:37 +01:00

14 KiB

Raw Permalink Blame History

📐 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 :

{
  "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 :

{
  "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 :

{
  "success": true,
  "message": "Shutdown en cours...",
  "timestamp": "2025-12-23T10:30:05Z"
}

3. Flux de Communication

3.1 Shutdown/Reboot

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

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

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 :

# 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 :

{
  "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

# 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

# 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)

14 KiB Raw Permalink Blame History

📐 Architecture MQTT pour IPWatch

1. Vue d'ensemble

1.1 Objectifs

1.2 Composants

2. Topics MQTT

2.1 Hiérarchie des Topics

2.2 Détail des Topics

ipwatch/device/{IP}/command

ipwatch/device/{IP}/status

ipwatch/device/{IP}/availability

ipwatch/device/{IP}/response

3. Flux de Communication

3.1 Shutdown/Reboot

3.2 Wake-on-LAN

3.3 Monitoring périodique

4. Gestion des Erreurs

4.1 Agent déconnecté

4.2 Commande non livrée

4.3 Agent en erreur

5. Sécurité

5.1 Authentification

5.2 Chiffrement TLS/SSL

5.3 ACL (Access Control List)

6. Performance et Scalabilité

6.1 Dimensionnement

6.2 Optimisations

7. Compatibilité Home Assistant

7.1 MQTT Discovery

7.2 Entités créées

8. Monitoring et Logs

8.1 Logs Agent

8.2 Logs Broker

8.3 Métriques

9. Diagrammes Détaillés

9.1 État de l'Agent

10. Références

11. TODO / Améliorations Futures

14 KiB

Raw Permalink Blame History

`ipwatch/device/{IP}/command`

`ipwatch/device/{IP}/status`

`ipwatch/device/{IP}/availability`

`ipwatch/device/{IP}/response`