Dépannage¶

Cette page est organisée par symptôme observé. Commencez par la section qui correspond à ce que vous constatez.

Méthode générale¶

flowchart TD
    A[Le service tourne-t-il ?] -->|non| B[journalctl : lire la dernière erreur]
    A -->|oui| C[L'agent est-il visible dans la Console ?]
    C -->|non| D[Problème d'enrôlement ou de liaison MQTT API]
    C -->|oui| E[Les valeurs remontent-elles ?]
    E -->|non| F[Problème de mapping ou de matériel]
    E -->|oui| G[Le problème est dans la logique D.L.S : voir le technicien]

Trois commandes couvrent 90 % des cas :

systemctl status abls-agent-<classe>@<tech_id>.service
sudo journalctl -u abls-agent-<classe>@<tech_id>.service -n 50
sudo journalctl -u abls-agent-<classe>@<tech_id>.service | grep local_config | tail -1

L'agent ne démarre pas¶

`There is no 'agent_tech_id', in config, exiting.`¶

Cause : aucune source n'a fourni de agent_tech_id.

Remède :

unité templatée : vérifier que vous avez bien démarré abls-agent-modbus@MON_ID.service et non abls-agent-modbus.service ;
unité simple (server, dls) : ajouter agent_tech_id dans /etc/abls/abls-agent.conf.

Warning

Le fichier /etc/abls/abls-agent-<classe>@<tech_id>.conf ne peut pas fournir le tech_id : son nom en dépend, il n'est lu qu'après.

`There is no 'api_url' / 'domain_uuid' / 'domain_secret'`¶

Cause : enrôlement incomplet ou fichier de configuration supprimé.

Remède : rejouer le --save avec toutes les options.

`Must be root to save config to ...`¶

Remède : relancer la commande avec sudo.

Le service redémarre toutes les 5 secondes¶

Restart=on-failure relance un agent qui quitte au démarrage. La cause réelle est la ligne juste avant l'arrêt :

sudo journalctl -u abls-agent-<classe>@<tech_id>.service -p err -n 30

L'agent démarre mais n'apparaît pas dans la Console¶

`POST_CONFIG from API Failed. Unloading.`¶

Trois causes possibles, à éliminer dans cet ordre :

L'API est injoignable.

curl -sS -o /dev/null -w '%{http_code}\n' https://api.abls-habitat.fr/status

L'horloge est décalée. L'horodatage entre dans le calcul de la signature.
```
timedatectl status
```
Sur un Raspberry Pi sans pile RTC, assurez-vous que la synchronisation aboutit avant le démarrage des agents.
Le domain_secret est faux. Recopiez-le depuis la Console, attention aux espaces en fin de chaîne lors d'un copier-coller.

`Agent disabled in API config. Unloading.`¶

L'agent existe côté API mais il y est désactivé. Réactivez-le dans la Console, page Agents.

Rien dans les journaux, mais l'agent reste « mort » dans la Console¶

La liaison MQTT vers l'API est tombée : le broker a publié le testament. Vérifiez le flux sortant vers le broker (port 1883 ou 8883) et, en TLS, la validité du certificat.

Problèmes TLS¶

Message	Cause	Remède
`Unable to find CA` au démarrage	`mqtt_over_ssl` actif, aucun magasin CA trouvé	Renseigner `mqtt_ca_file`
`certificate verify failed`	Autorité privée non reconnue	Déclarer le CA dans `mqtt_ca_file`, ou l'installer dans le magasin système
Erreur TLS sur l'appel HTTPS de l'API	Certificat de l'API émis par une autorité privée	`update-ca-certificates` (Debian) ou `update-ca-trust` (Fedora)

Un paramètre semble ignoré¶

C'est presque toujours un problème de précédence.

Rappel : ARGV > FILE > ENV > défaut. Une variable d'environnement est donc écrasée par le fichier de configuration.

# Ce que l'agent a réellement retenu
sudo journalctl -u abls-agent-<classe>@<tech_id>.service | grep local_config | tail -1

# D'où viennent les valeurs
sudo journalctl -u abls-agent-<classe>@<tech_id>.service | grep -E "Apply ENV|Trying to read"

Voir Configuration et précédence.

Pièges fréquents :

une variable ABLS_* restée dans le shell au moment du --save a été figée dans le fichier ;
--tps 0 est ignoré (une option entière valant zéro n'est pas appliquée) ;
un drapeau ne sait que passer à true : il n'existe pas de --no-dry-run ;
une clé présente dans abls-agent.conf masque définitivement la même clé du fichier abls-agent-<classe>@<tech_id>.conf.

Deux agents se marchent dessus¶

Symptôme : les valeurs oscillent, un agent se déconnecte quand l'autre se connecte.

Cause : deux processus partagent le même agent_tech_id, donc le même compte MQTT et les mêmes topics.

Remède : ne jamais placer agent_tech_id dans le fichier commun /etc/abls/abls-agent.conf si la machine porte plusieurs instances d'une même classe.

Les entrées remontent mais les sorties ne s'actionnent pas¶

Les sorties transitent par le bus MQTT local, pas par l'API.

# Sur le serveur master : les commandes arrivent-elles ?
mosquitto_sub -h <master> -t 'SET_DO/#' -v
mosquitto_sub -h <master> -t 'SET_AO/#' -v

Observation	Conclusion
Aucune commande ne circule	Le problème est en amont : moteur D.L.S ou mapping (voir le technicien)
Les commandes circulent mais rien ne bouge	Problème d'agent ou de matériel
Les commandes circulent sur un autre `tech_id`	Erreur de mapping dans la Console

Vérifiez également que dry_run n'est pas resté actif :

sudo journalctl -u abls-agent-<classe>@<tech_id>.service | grep -i 'dry-run'

Le message Dry-run mode enabled. au démarrage indique que l'agent n'écrit rien volontairement.

Le moteur D.L.S ralentit¶

Symptôme : dans le tableau de bord de la Console, les tours par seconde tombent sous la consigne.

Pistes :

machine sous-dimensionnée ou surchargée (top, uptime) ;
log_level resté à 7 : le volume de journalisation étrangle le moteur ;
disque saturé ou très lent (carte SD usée sur Raspberry Pi) ;
module D.L.S coûteux introduit récemment — à qualifier avec le technicien.

sudo journalctl --disk-usage
df -h

Le disque se remplit¶

Coupable	Vérification	Remède
Journaux systemd	`journalctl --disk-usage`	`sudo journalctl --vacuum-size=500M`, baisser `log_level`
Base d'archives	Taille des bases MariaDB	Réduire la rétention dans la Console, puis `OPTIMIZE TABLE`
Sauvegardes	`du -sh /var/backups`	Mettre en place une rotation

Quand ce n'est pas un problème d'administration¶

Certains symptômes relèvent du technicien, pas de l'administrateur :

Symptôme	Volet concerné
Une valeur est lue mais sous le mauvais nom	Mapping des I/O
Un automatisme ne se déclenche pas	Modules D.L.S
Un visuel ne s'anime pas	Synoptiques
Un message n'est pas envoyé par SMS	Messages

Rassembler les éléments avant de demander de l'aide¶

{
  echo "=== Version"
  dpkg -l 'abls-*' 2>/dev/null || rpm -qa 'abls-*'
  echo "=== Services"
  systemctl list-units 'abls-agent-*' --all --no-pager
  echo "=== Journaux"
  journalctl -u 'abls-agent-*' -n 200 --no-pager
} > /tmp/abls-diag.txt

Avant d'envoyer ce fichier

Retirez-en toute occurrence du domain_secret et des mots de passe MQTT :

grep -i 'secret\|password' /tmp/abls-diag.txt