À quoi ça sert. Un guide de terrain tiré des incidents récents. Chaque entrée se lit symptôme, cause, vérifier, corriger. Les numéros de version disent à partir de quelle version du paquet la cause est corrigée dans la source ; sur une box plus ancienne, mettre d'abord le paquet à jour (voir Operations-APT-Repository-FR).

#	Symptôme	Section
1	disque plein	Disque plein
2	minuteur sans prochaine échéance	Minuteurs
3	routes neuves en 404 / redémarrage de l'agrégateur	Agrégateur
4	le WAF n'écrit plus ses journaux	Journaux sbxwaf
5	WAF « hors service » alors qu'il tourne	État du WAF
6	certificats valides affichés expirés	Certificats
7	stats réseau toujours « périmées »	Stats réseau
8	module en boucle, socket périmée	Sockets
9	nginx ne démarre pas	nginx :80

• Symptôme. Des services n'écrivent plus, dpkg ne peut plus écrire son propre fichier d'état, des paquets restent non configurés, les interfaces répondent en 5xx. Vu sur un poste de construction et sur une image full trop petite (les tailles de construction sont maintenant 8G pour isp, 12G pour full).
• Cause. Sur un poste de développement : worktrees d'agents et sorties de construction accumulés. Sur une box : racine trop petite et données au mauvais endroit (médias et caches vont sur le disque de données).
• Vérifier. df -h, puis du -xh --max-depth=1 / sur le volume plein. Pour les worktrees : scripts/agent-worktree.sh list --verbose.
• Corriger. Retirer les worktrees terminés par scripts/agent-worktree.sh clean <issue> (il refuse un worktree sale ou une branche dont la PR n'est pas fusionnée, sauf --force). Avant de supprimer un worktree à la main, regarder ce que git ignore (git status --ignored) : un motif .gitignore non ancré peut cacher de vrais fichiers source. Vider le cache apt avec apt-get clean. Ne jamais libérer de place en supprimant sous /etc/secubox ou /var/lib/secubox.

• Symptôme. Une tâche ne tourne jamais ; systemctl list-timers --all affiche n/a dans la colonne NEXT pour un minuteur SecuBox.
• Cause. L'unité minuteur n'est pas active (non activée, arrêtée par une mise à jour de paquet, ou en échec), ou un minuteur piloté seulement par OnUnitActiveSec= dont le service n'a jamais tourné n'a rien à compter. Le postinst d'un paquet doit relancer une unité que la mise à jour a arrêtée.
• Vérifier. systemctl list-timers --all, systemctl status <nom>.timer, et la cadence effective avec systemctl cat <nom>.timer (les drop-ins de cadence 10-cadence.conf viennent de secubox-core ; ils remettent d'abord OnUnitActiveSec= à zéro puis posent le nouvel intervalle, avec un RandomizedDelaySec=).
• Corriger. systemctl daemon-reload après tout changement de drop-in, puis systemctl enable --now <nom>.timer. Un paquet qui laisse son minuteur arrêté après une mise à jour a un défaut de postinst : le signaler avec la version.

• Symptôme. Une route neuve ou modifiée d'un module répond 404, ou tout un ensemble de routes /api/v1/<module>/ répond 502.
• Cause. secubox-aggregator importe au démarrage le code de chaque module agrégé (environ 110 modules dans un seul processus, aucun ne porte son propre démon). Le nouveau code d'un module n'est pris en compte qu'après le redémarrage de l'agrégateur. Le démarrage à froid est long et les sockets sont indisponibles pendant ce temps.
• Vérifier. systemctl is-active secubox-aggregator ; journalctl -u secubox-aggregator pour les erreurs d'import. Un module à sa propre socket est indépendant de l'agrégateur.
• Corriger. systemctl restart secubox-aggregator. Compter une coupure d'environ 40 secondes pour tous les modules agrégés ; la planifier, et ne jamais redémarrer en parallèle de nombreux démons secubox-*. Le watchdog laisse 480 s de grâce au démarrage avant son auto-réparation : ne pas relancer tant que le chargement n'est pas fini.

• Symptôme. /var/log/secubox/waf/waf-threats.log ne grossit plus ; les panneaux du WAF se vident alors que le trafic passe.
• Cause. Le dossier de journaux a perdu son propriétaire ou son mode. Il doit être secubox-waf:secubox-waf, mode 0750 ; le parent partagé /var/log/secubox reste en 0755 (le passer en 0750 casse la traversée pour les autres services). Le dossier de cache /var/cache/secubox/waf a le même propriétaire.
• Vérifier. ls -ld /var/log/secubox /var/log/secubox/waf /var/cache/secubox/waf ; journalctl -u secubox-waf-ng.
• Corriger. Réinstaller ou mettre à jour secubox-waf-ng (son postinst recrée les dossiers avec le bon propriétaire et le bon mode ; l'unité prépare elle-même le cache depuis la 1.27.3), puis systemctl restart secubox-waf-ng. Pas de drop-in écrit à la main : un drop-in corrompu (backticks dans un heredoc non protégé) a déjà cassé l'unité.

• Symptôme. La santé globale (portail, bandeau) annonce le WAF hors service alors que sbxwaf tourne.
• Cause. Le contrôle regardait encore l'ancien conteneur mitmproxy. Depuis secubox-metrics 1.19.1 (#2391), l'état suit secubox-waf-ng (service actif et port 8085 qui répond).
• Vérifier. systemctl is-active secubox-waf-ng et ss -ltn pour le port 8085 en boucle locale.
• Corriger. Mettre secubox-metrics à 1.19.1 ou plus. Si le service est réellement arrêté, systemctl restart secubox-waf-ng (un redémarrage, pas un signal de rechargement).

• Symptôme. La page Certificats montre des certificats valides comme expired (moins 999 jours).
• Cause. Des fichiers de /data/haproxy/certs étaient root en 0600 : l'API tourne en secubox et ne pouvait pas les lire, et un fichier illisible comptait comme expiré (#2383). secubox-certs 1.2.8 l'affiche maintenant unknown (« illisible »), et secubox-haproxy 1.10.3 écrit les .pem en 0640 haproxy:secubox, comme certsctl deploy.
• Vérifier. ls -l /data/haproxy/certs.
• Corriger. Mettre les deux paquets à jour, puis rendre les fichiers existants lisibles par le groupe (chown haproxy:secubox, chmod 0640). Un échec de lecture n'est plus mémorisé : le passage suivant les reprend.

• Symptôme. « Réseau en direct » du SOC et l'onglet Réseau du Toolbox affichent « COLLECTEUR ARRÊTÉ ? » alors que le collecteur tourne.
• Cause. Le seuil de péremption était inférieur à la cadence du collecteur. Le minuteur secubox-netstats.timer passe toutes les 120 s plus jusqu'à 30 s de délai aléatoire. secubox-hub 1.9.55 (#2388) porte le seuil à 360 s (deux cadences plus une marge), lié au drop-in de cadence par un test.
• Vérifier. systemctl cat secubox-netstats.timer ; comparer l'intervalle au seuil. Si vous ralentissez la cadence, relevez le seuil au-delà de deux cadences.
• Corriger. Mettre secubox-hub à 1.9.55 ou plus. Si le collecteur est vraiment arrêté : systemctl status secubox-netstats.timer.

• Symptôme. Un module redémarre en boucle avec Unable to check or remove stale UNIX socket: PermissionError(1) puis Address already in use ; ses routes répondent 502. Ou beaucoup de modules perdent leur socket d'un coup après un redémarrage.
• Cause. /run/secubox est partagé par environ 95 unités et collant (1777, root:root) : un processus ne peut délier que ce qu'il possède, donc une socket laissée par un autre utilisateur bloque le démon. Le défaut inverse, RuntimeDirectory=secubox dans une unité, efface au redémarrage les sockets de tous les voisins.
• Vérifier. ls -l /run/secubox. Pour le réglage effectif (jamais par grep, les commentaires donnent des faux positifs) : systemctl show <unité> -p RuntimeDirectory -p RuntimeDirectoryPreserve --value.
• Corriger. Toute unité qui lie une socket ici porte ExecStartPre=+/bin/rm -f /run/secubox/<module>.sock (le + l'exécute en root). Jamais de chown du parent, jamais de RuntimeDirectory=secubox. Règles : section 2 du fichier RULES-CODE.md du dépôt.

• Symptôme. nginx échoue avec bind() to 0.0.0.0:80 failed (98: Address already in use), et tous les vhosts de l'hôte tombent avec lui. Cela peut rester invisible des semaines, car un reload ne rebind pas.
• Cause. Sur une SecuBox, HAProxy détient 0.0.0.0:80 (et :443). Tout vhost hôte avec listen 80 empêche nginx de démarrer ; le premier vrai redémarrage échoue alors.
• Vérifier. nginx -t, puis chercher listen 80 dans les vhosts activés. Plusieurs instances nginx peuvent aussi tourner dans des conteneurs : vérifier le cgroup avant de tuer un processus.
• Corriger. Faire écouter le vhost sur le port de son module (la chaîne HAProxy puis sbxwaf y route déjà) et redémarrer nginx. Le trafic doit passer par sbxwaf : pas de contournement à la main (seulement le waf_bypass = true déclaratif par vhost dans /etc/secubox/haproxy.toml). Voir WAF-FR.

Operations-APT-Repository-FR · Operations-Release-Process-FR · Troubleshooting-FR · FAQ-Troubleshooting · WAF-FR · Profils · Operations-Runbook