07 Runbook opérations

Diagnostic et recovery sur incidents en production

Symptômes à observer côté Indaba alerting

Alerte Indaba	Cause probable	Action runbook
`life_counter` figé entre 2 health POSTs	Flow LuvitRED bloqué ou crashed	§ Flow freeze
Pas de health POST reçu depuis 1 h	WAN down OR auth DAP perdue OR CG down	§ Health silent
401 répétés sur uplinks	Token DAP invalide/expiré, retry auto en boucle	§ DAP 401 loop
425 sur Token	Device pas encore validé par Jean-Marc dans IoBase portal	§ DAP pending validation
Asystom 401	Mauvais credentials Basic auth	§ Asystom auth
Pas d'uplink balise depuis > 30 min	Balise morte, trop loin, magnet à refaire	§ Balise silencieuse

Flow freeze (life_counter figé)

SSH la CG : ssh admin@<ip>
Vérifier que LuvitRED tourne : ps | grep luvit
Si crashé : /etc/init.d/luvitred restart (au boot suivant le flow se reload + restore tokens)
Si le flow tourne mais figé : ouvrir LuvitRED admin, regarder le debug sidebar pour erreurs Lua
Last resort : factory reset → re-provisionner depuis CloudGate Universe → re-enrôlement DAP avec Jean-Marc

Health silent

Check WAN : depuis l'admin CG /api/internetConnection → connectionStatus: 1 attendu
Si WAN OK mais health silent : check tokens DAP (§ DAP 401)
Si WAN KO : c'est attendu, les health sont en queue offline (15 j max)
Vérifier que le canvas debug montre les HEALTH_OUT + HEALTH_RESP alternés

DAP 401 loop

Comportement normal du canvas :

POST IoBase prend 401
handle_iobase_resp détecte → fn_trigger_refresh_on_401 → build_dap_refresh (mutex)
POST /refresh → nouveaux tokens
Trame en queue replay automatiquement avec le nouveau token

Pathologies à investiguer :

Refresh KO 401 : refresh_token consommé deux fois (single-use violation). Recovery = re-enrôlement complet avec Jean-Marc (suppression device dans portail IoBase + register from scratch).
Refresh KO 500 : serveur DAP down. Attendre + alerter Terega.
Boucle persistante : le mutex protège contre les refresh en rafale. Si on voit néanmoins une boucle, vérifier que handle_dap_resp reset bien global.dap_refreshing sur erreur.

DAP 425 — pending admin validation

Au premier enrôlement seulement. Réponse 425 Authorization Pending sur /Token = Jean-Marc n'a pas encore validé le device dans le portail IoBase.

Action : appeler Jean-Marc, lui demander de :

Se connecter à IoBase
⚙ Settings → « Services et équipements »
Trouver le device cloudgate-terega-XX (statut Attente de validation)
Cliquer « Valider l'équipement » + sélectionner un compte de service dédié + valider
Côté CG, retirer l'inject DAP get token

Asystom 401

Asystom utilise Basic auth (pas DAP). Un 401 = mauvais credentials. Le canvas ne déclenche pas le refresh DAP dans ce cas (depuis le fix tâche #29).

Action : vérifier global.asystom_auth_b64 avec Patrick Duc, regenerate base64 si nécessaire :

echo -n "user:password" | base64

Balise silencieuse

Vérifier dans LuvitRED admin → LoRa → OTA Devices → la balise est-elle marquée Joined ?
Si oui mais pas d'uplink : balise endormie (cadence trop longue ou en hibernation)
- Tirer downlink reboot (FPort 64) pour forcer un nouveau cycle
- Ou tirer downlink set freq (FPort 70) pour réduire la cadence
Si non marquée Joined : refaire la séquence magnet × 3 sur la balise. Vérifier piles.
Si pas dans la liste : pas enrôlée. Voir Chap. 05.

Maintenance préventive

Tâche	Cadence	Comment
Audit jsonl rotation	Quotidien 02:00 UTC	Automatique par cron canvas. Garde 15 jours, supprime au-delà.
DAP refresh	Toutes les 50 min	Automatique par cron + retry sur 401 + WAN-up.
life_counter persist	Toutes les 60 s	Automatique. Restauré au boot.
Backup canvas	Manuel, après chaque modification	Exporter `flows.json` via LuvitRED admin → Export.
Vérification stockage	Mensuel	`df -h /mnt/data /overlay` via SSH. `/mnt/data` < 80% utilisé attendu.
Vérification tokens DAP	Mensuel	`cat /mnt/data/luvitred/dap_state.json` + check `saved_at` < 24 h.

Backup & restore

Backup canvas + tokens (avant modif)

# Mac
SSH_OPTS="-o KexAlgorithms=+diffie-hellman-group1-sha1 -o HostKeyAlgorithms=+ssh-rsa -o PubkeyAcceptedAlgorithms=+ssh-rsa"

# Flow LuvitRED
curl -b /tmp/lc.cookies http://<cg-ip>:8080/flows > backup-flows-$(date +%s).json

# Tokens + state
sshpass -p '...' scp $SSH_OPTS \
  admin@<cg-ip>:/mnt/data/luvitred/dap_state.json \
  ./backup-dap-$(date +%s).json

# Audit récent
sshpass -p '...' scp $SSH_OPTS -r \
  admin@<cg-ip>:/mnt/data/luvitred/uplinks-*.jsonl \
  ./backup-audit/

Restore après corruption flow

# 1. Restore flow
curl -b /tmp/lc.cookies -X POST -H "Content-Type: application/json" \
   -d @backup-flows-XXX.json http://<cg-ip>:8080/flows

# 2. Restore tokens
sshpass -p '...' scp $SSH_OPTS \
   backup-dap-XXX.json admin@<cg-ip>:/mnt/data/luvitred/dap_state.json

# 3. Re-deploy via LuvitRED admin → Deploy
# 4. Vérifier DAP_RESTORE_OK dans le debug sidebar