net-hw-watchdog

net-hw-watchdog surveille une interface réseau Linux et tente de restaurer la connectivité lorsque le pilote ou la carte réseau se bloque.

Deux profils sont pris en charge : les cartes Intel utilisant le pilote e1000e (incidents de type Hardware Unit Hang) et les cartes wifi Marvell en SDIO utilisant le pilote mwifiex_sdio (incidents de type crash firmware : mwifiex_cmd_timeout_func, PREP_CMD: FW is in bad state, boucle de réinitialisation _mwifiex_fw_dpc).

Fonctionnement

Le watchdog reprend le comportement du watchdog historique de Terry dans une implémentation Python configurable :

1. surveiller le journal noyau pour détecter un incident associé à l'interface ou au périphérique PCI configuré ;
2. enregistrer un snapshot de diagnostic ;
3. vérifier la connectivité avant toute action ;
4. si nécessaire, exécuter les étapes du plan de récupération dans l'ordre ;
5. retester la connectivité après chaque étape et s'arrêter dès qu'elle revient ;
6. enregistrer le résultat et envoyer éventuellement des notifications ntfy.

Un événement provenant d'une autre carte utilisant le même pilote ne déclenche pas la récupération de l'interface surveillée.

Le basculement vers une seconde carte réseau n'est pas encore implémenté.

Configuration YAML

La configuration système est prévue dans :

/etc/asami/net-hw-watchdog.yaml

Un exemple complet est fourni dans config/net-hw-watchdog.yaml.example.

Le plan de récupération est une liste ordonnée :

remediation:
  enabled: true
  plan:
    - link-renegotiate
    - link-cycle
    - module-reload

remediation.enabled remplace l'ancien --armed. La liste plan remplace les anciens arguments --allow-*.

Les actions disponibles sont :

• link-renegotiate : demande une renégociation par ethtool -r ;
• link-cycle : descend puis remonte l'interface physique et demande ensuite un networkctl renew ciblé lorsque networkctl est disponible ;
• module-reload : retire puis recharge le module réellement associé à l'interface surveillée ; avant le retrait, le watchdog vérifie via sysfs que ce module ne pilote aucune autre interface et refuse l'action si cette exclusivité n'est pas démontrée ;
• pci-rebind : détache puis rattache le périphérique PCI à son pilote.
• reboot : planifie un redémarrage de la machine via systemctl reboot. L’action est nécessairement la dernière du plan (refusée par la validation de configuration sinon), --check exige alors systemctl, un snapshot before-reboot est collecté et la notification « Network recovery reboot » est envoyée avant l’extinction. En dry-run la commande est ignorée et aucun redémarrage n’est signalé. Réservé aux machines dont le rôle rend un reboot acceptable (par exemple une tablette kiosk qui restaure sa session au démarrage).

Le redémarrage global de systemd-networkd ne fait pas partie du plan.

Chaque commande corrective est contrôlée individuellement. Un retour non nul produit un diagnostic ACTION_FAILED avec le code de sortie et le message disponible ; l'étape n'est pas considérée comme exécutée avec succès.

Notifications

Lorsqu'un serveur ntfy est configuré, chaque notification de récupération inclut le nom de la machine et l'interface surveillée, dans le titre et le corps du message :

[Sekitan] Network recovered (mlan0)
Connectivity on mlan0 returned after link-cycle.

Interface physique et connectivité

L'interface surveillée et l'interface utilisée pour tester la connectivité peuvent être différentes.

Par exemple, si enp0s31f6 est membre du bridge br0 :

watch:
  interface: enp0s31f6
  expected_driver: e1000e

connectivity:
  interface: br0
  target: 192.168.1.250

Les valeurs auto sélectionnent la route par défaut et sa passerelle. Le contrôle vérifie alors que l'interface physique est cohérente avec l'interface de connectivité.

Commandes

Vérifier la configuration et les invariants de la machine sans aucune mutation :

sudo net-hw-watchdog --check

Analyser une fois les messages noyau récents :

sudo net-hw-watchdog --once

Surveiller les nouveaux messages noyau en continu :

sudo net-hw-watchdog --monitor

Forcer un passage dans le chemin de récupération sans exiger de message noyau correspondant :

sudo net-hw-watchdog --once --force

Empêcher toute action réseau même lorsque remediation.enabled: true :

sudo net-hw-watchdog --once --dry-run

En dry-run, les snapshots, lectures du journal et tests de connectivité restent actifs ; les commandes de récupération et les notifications sont ignorées.

Qualification synthétique du plan complet

Pour parcourir tout le plan sans couper le réseau, le probe de connectivité peut être forcé à DOWN :

sudo net-hw-watchdog --once --force --dry-run --simulate-connectivity-down

Ce mode est volontairement limité à la combinaison --once --force --dry-run. Il n'est pas configurable dans le YAML et il est refusé en mode --monitor ou sans --dry-run.

Dans ce mode :

• aucun ping n'est envoyé ;
• chaque probe retourne volontairement DOWN ;
• chaque action du plan est affichée puis ignorée par le dry-run ;
• aucune notification externe n'est envoyée ;
• le résultat final Network recovery failed est attendu, puisque la simulation maintient la connectivité à DOWN.

Diagnostics

Chaque exécution crée :

• un journal horodaté ;
• les messages noyau lus ;
• les snapshots réseau et pilote ;
• si output.archive: true, une archive tar.gz des données de diagnostic.

Le répertoire par défaut est :

/var/log/asami/net-hw-watchdog

Aucun token ni mot de passe ntfy n'est écrit dans les logs ou snapshots.

État du projet

L’état courant des déploiements, qualifications et prochains tests est maintenu dans STATE.md.

La parité fonctionnelle du watchdog Terry est en cours de validation. Aucun mécanisme de basculement automatique vers une seconde carte réseau n'est encore implémenté.

Une unité systemd est fournie dans systemd/asami-net-hw-watchdog.service. Elle exécute --check avant chaque démarrage puis lance --monitor.

La première configuration d'observation Hiko est fournie dans systemd/hiko-observation.yaml avec remediation.enabled: false : elle surveille et collecte les diagnostics sans exécuter de commande de récupération.

Développement

Le programme nécessite Python 3.11 ou ultérieur et PyYAML.

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

Licence

Ce projet est distribué sous licence GNU General Public License v3.0 ou ultérieure (GPL-3.0-or-later).

Voir LICENSE.