🔧 Dépannage des sondes
Identifier la cause d'une sonde en erreur (Basic / Étendu / Push) et la tester, étape par étape
Cette page aide à diagnostiquer une sonde qui ne remonte pas de données (ou plus) : Basic (/status.php), Étendu (API serverinfo) ou Push (script cron sur l'instance distante). Démarche en 3 temps : repérer le symptôme dans l'interface, comprendre la cause probable, puis tester indépendamment de NcStatusCheck pour confirmer avant de changer une configuration.
Les commandes exactes pour configurer un token serverinfo ou déployer le script Push sont déjà documentées dans les sections dépliantes « 🛠️ Sonde Étendue » et « 📡 Sonde Push » de la page Admin — cette page ne les répète pas, elle vous y renvoie une fois la cause identifiée.
1. Repérer le symptôme : la colonne Sondes du tableau de bord
La colonne Sondes du tableau de bord condense l'état de chaque sonde configurée. Un badge violet ou bleu = tout va bien ; un badge orange avec une icône = quelque chose ne remonte plus. Exemple avec plusieurs serveurs de démonstration couvrant tous les cas :
| Badge observé | Signification | Aller à |
|---|---|---|
| ⚡ Étendu | Sonde Étendue fonctionnelle, données à jour | — |
| ⚡ Étendu ⚠ | Erreur de connexion à l'API serverinfo (token, app non installée, réseau…) | 3. Mode Étendu |
| ⚡ Étendu 🕐 | Dernière collecte réussie il y a plus de 26h | 3. Mode Étendu |
| 📡 Push | Sonde Push fonctionnelle, données récentes | — |
| 📡 Push ⚠ | Aucune donnée jamais reçue de cette instance | 4. Mode Push |
| 📡 Push 🕐 | Dernière réception plus ancienne que l'intervalle configuré (+ 30 min de grâce) | 4. Mode Push |
| 📡 Push ↑ | Le script installé sur l'instance est plus ancien que la version courante | 4. Mode Push |
| — | Aucun token configuré (mode Basic pur) — normal, ce n'est pas une panne | 2. Mode Basic |
| 🔴 Hors ligne | Colonne Santé (pas Sondes) : le serveur ne répond plus depuis 2 sondes consécutives | 2. Mode Basic |
2. Mode Basic — rien ne remonte / serveur hors ligne
Le mode Basic interroge /status.php et lit les en-têtes HTTP (Server, X-Powered-By). C'est le socle commun à tous les serveurs — même Étendu et Push s'y replient en cas d'échec. Un problème ici affecte donc potentiellement les autres modes aussi.
📄 Fichier concerné : en mode Basic pur, l'entrée du serveur dans servers.json (à la racine de l'installation NcStatusCheck) ne contient que l'URL — pas de token à vérifier : {"url": "https://votre-nextcloud.tld"}.
Étape 1 — tester depuis un poste quelconque, indépendamment de NcStatusCheck
Réponse attendue : HTTP/1.1 200 et un JSON contenant "installed":true et "versionstring":"…". Si cette commande échoue déjà depuis votre poste, le problème est réseau/serveur côté Nextcloud (pare-feu, certificat expiré, service arrêté) — pas un bug de NcStatusCheck.
Étape 2 — si le curl marche mais pas le monitoring
Le problème est alors spécifique à NcStatusCheck : IP du serveur qui héberge NcStatusCheck bloquée par un pare-feu/WAF côté Nextcloud, résolution DNS différente, ou détection anti-SSRF (voir §7). Direction : cache/monitor.log (voir §6) — cherchez la ligne cURL error for … ou HTTP failure for … (code: …) pour le message exact.
? gris dans la colonne Santé ne veut pas dire « panne » : c'est juste l'absence de sonde Étendue/Push (mode Basic pur, aucune donnée détaillée à afficher). Le badge 🔴 Hors ligne, lui, vient d'un suivi indépendant (uptime_state.json) : le serveur bascule « down » après 2 sondes consécutives en échec (par défaut), et remonte « up » dès la première sonde réussie.
3. Mode Étendu (serverinfo) — badge orange
Interroge /ocs/v2.php/apps/serverinfo/api/v1/info avec l'en-tête NC-Token. Le champ interne extended_error n'est qu'un drapeau — il ne stocke pas le message d'erreur détaillé, seulement vrai/faux. Pour le motif exact, utilisez le bouton « Tester » ou consultez les logs.
📄 Fichiers concernés
L'entrée du serveur dans servers.json (racine de l'installation NcStatusCheck) porte le token :
Modifiable à la main (JSON strict, une virgule ou un guillemet manquant invalide tout le fichier) mais l'interface admin reste plus sûre. Après un succès, la réponse brute est mise en cache dans cache/serverinfo_<md5(url)>.json — supprimer ce fichier force une nouvelle collecte au prochain rafraîchissement (md5 de l'URL exacte, calculable via php -r "echo md5('https://votre-nextcloud.tld');").
Étape 1 — le bouton « Tester » de la carte serveur (admin)
Étape 2 — tester manuellement (indépendant de NcStatusCheck)
| Résultat | Cause probable | Action |
|---|---|---|
HTTP 401 / 403 |
Token invalide, révoqué, ou différent de celui enregistré côté Nextcloud | Régénérer le token via occ config:app:set serverinfo token --value "…" (voir la section dépliante « 🛠️ Sonde Étendue » dans l'admin) et le mettre à jour dans NcStatusCheck |
HTTP 404 |
L'app Monitor/serverinfo n'est pas installée ou désactivée sur l'instance | occ app:enable serverinfo |
| Timeout / DNS / SSL | Problème réseau — mêmes causes que le mode Basic | 2. Mode Basic |
| 200 mais réponse invalide | JSON tronqué, proxy qui altère la réponse, ou incompatibilité de version Nextcloud | Rejouer la commande curl ci-dessus et inspecter le corps brut de la réponse |
/status.php pour au moins afficher une version. Le badge reste orange même si une version Nextcloud s'affiche à nouveau dans le tableau : ne vous fiez pas à la présence d'une version pour conclure que tout va bien, seul le badge Sondes fait foi.
4. Mode Push — badge orange ou marqueur ↑
Le Push est piloté par un cron sur l'instance Nextcloud distante, pas par NcStatusCheck : un badge orange ici signifie le plus souvent que le script distant ne s'exécute plus ou échoue, rarement un problème du monitor lui-même.
📄 Fichiers concernés
Côté NcStatusCheck (monitor) : l'entrée du serveur dans servers.json porte le token, et le dernier envoi reçu est mis en cache tel quel :
Côté instance Nextcloud (distant), tout est suffixé par un slug dérivé de l'URL surveillée (affiché par l'admin lors de la génération du script, ex. latest.ezeo.coop → latest_ezeo_coop) :
Le script /usr/local/bin/ncstatuscheck-push.sh lui-même est générique et partagé par toutes les instances de cet hôte (une seule copie à mettre à jour) ; seul le .conf change d'une instance à l'autre.
Étape 1 — sur l'instance Nextcloud : cron et log du script
Cherchez OK: data sent to … (envoi réussi) ou ERROR: send failed to … — <réponse> (la réponse brute de push-api.php est incluse — elle contient le motif exact).
Étape 2 — rejouer manuellement
--test valide la configuration sans rien pousser (dépendances curl/jq/md5sum, fonctionnement de occ, présence du fichier targets-<instance>.conf). Une fois corrigé, relancez sans --test pour un envoi réel immédiat.
| Réponse de push-api.php | Cause probable | Action |
|---|---|---|
401 err_push_token_invalid |
Couple URL + token incorrect dans targets-<instance>.conf (token régénéré côté monitor sans mettre à jour la cible) |
Régénérer/copier le token Push depuis la carte serveur (admin) et mettre à jour la ligne targets correspondante |
400 err_push_timestamp_invalid |
Horloge de l'instance Nextcloud désynchronisée de plus de 24h | date / vérifier NTP (timedatectl) |
400 err_push_url_missing |
Fichier de config d'instance incomplet (SERVER_URL manquant) |
Vérifier /etc/ncstatuscheck/<instance>.conf |
413 err_push_body_too_large |
Payload supérieur à 1 Mo (rare — beaucoup d'apps/conteneurs) | À signaler — pas résoluble côté configuration |
500 err_push_write |
Écriture cache impossible côté monitor (permissions cache/) |
Problème serveur NcStatusCheck, pas côté Nextcloud — vérifier les permissions du dossier cache/ |
occ passe par docker exec : OCC_CMD=docker exec -u www-data <conteneur> php occ (AIO : nextcloud-aio-nextcloud). Deux pièges : ne jamais ajouter -t (pas de TTY sous cron) et garder -u www-data (l'image officielle refuse occ en root). Test d'isolement : docker exec -u www-data <conteneur> php occ status --output=json — si du JSON sort, seul OCC_CMD est en cause, pas Docker.
5. Tester à la main, indépendamment de NcStatusCheck
Avant de changer une configuration, isolez d'où vient le problème : ces trois commandes ne dépendent pas de NcStatusCheck et peuvent être lancées depuis n'importe quel poste ayant accès au Nextcloud concerné (ou en SSH sur l'instance elle-même pour la dernière).
Si ces commandes réussissent mais que NcStatusCheck affiche toujours une erreur, le problème est spécifique au monitor (réseau sortant, anti-SSRF, cache) — direction les logs (§6).
6. Où trouver l'information : logs et fichiers de configuration
| Fichier | Contenu | Format |
|---|---|---|
cache/monitor.log |
API HTTP (api.php) : chaque requête get_data/refresh_data, erreurs cURL et HTTP par serveur |
[date] [NIVEAU] [IP] message |
cache/cron.log |
Collecte complète planifiée (cron-update.php, 2×/jour) |
[date] [NIVEAU] [PID:n] message |
cache/ping.log |
Sonde de joignabilité légère (cron-ping.php, toutes les 5 min) — up/down uniquement |
[date] [NIVEAU] [PID:n] message |
/var/log/ncstatuscheck-push-<instance>.log |
Côté instance Nextcloud distante (pas sur le monitor) : résultat de chaque tentative de push, par cible | OK: data sent to … / ERROR: send failed to … — … |
Les logs sont bornés à 5 Mo (rotation automatique en .old). Les identifiants éventuellement présents dans une URL (user:pass@) sont systématiquement masqués avant écriture — jamais en clair.
Fichiers de configuration
En complément des logs, ces fichiers contiennent la configuration effective — consultables (et modifiables) directement, sans passer par l'interface :
| Côté | Fichier | Contenu |
|---|---|---|
| Monitor | servers.json |
Liste des serveurs surveillés + tokens (serverinfo_token, push_token, auto_push_interval) |
| Monitor | config.php |
Constantes globales : PUSH_SCRIPT_VERSION (marqueur ↑), CACHE_MAX_AGE, UPTIME_FAIL_THRESHOLD (seuil hors ligne) — ignoré par git |
| Monitor | cache/serverinfo_<md5(url)>.json |
Dernière réponse serverinfo brute reçue (mode Étendu) — supprimer force une nouvelle collecte |
| Monitor | cache/push_<md5(url)>.json |
Dernier payload Push reçu — supprimer réinitialise « aucune donnée reçue » |
| Monitor | cache/uptime_state.json |
État up/down par URL : {state, since, last_check, fail_streak} |
| Nextcloud distant | /etc/ncstatuscheck/<instance>.conf |
Config de cette instance : SERVER_URL, SLUG, OCC_CMD, DOCKER_ENABLED, SKOPEO_ENABLED |
| Nextcloud distant | /etc/ncstatuscheck/targets-<instance>.conf |
Un monitor par ligne : url|push_token[|user|pass] (chmod 600, contient des tokens) |
| Nextcloud distant | /etc/cron.d/ncstatuscheck-<instance> |
Planification du script Push (fréquence choisie à la génération) |
Les noms de cache monitor utilisent le md5 de l'URL exacte du serveur — le calculer avec php -r "echo md5('https://votre-nextcloud.tld');" ou echo -n "https://votre-nextcloud.tld" | md5sum.
7. Erreur réseau normale ou blocage de sécurité volontaire ?
Lors de l'ajout ou du test d'un serveur, un message d'erreur en anglais brut (contrairement aux autres messages, en français) signale un refus volontaire de NcStatusCheck — pas un problème réseau à corriger côté Nextcloud :
| Message observé | Signification |
|---|---|
Invalid URL: only https:// is accepted |
L'URL n'est pas en https:// |
Invalid URL: credentials (user:pass@) are not accepted |
L'URL contient des identifiants intégrés |
Rejected URL: local host forbidden |
Le nom d'hôte est localhost ou équivalent |
Rejected URL: internal address |
L'IP résolue est privée/interne (RFC1918, loopback, link-local) — NcStatusCheck refuse par principe de sonder un réseau interne, même le sien |
Ce garde s'applique aussi après une redirection HTTP (une instance qui redirige vers une IP interne est bloquée en cours de requête). C'est un comportement voulu (anti-SSRF) : il n'y a rien à « réparer » côté Nextcloud, l'URL surveillée doit simplement être une adresse publique valide.
8. Tableau récapitulatif — symptôme → cause probable → action
| Symptôme | Cause probable | Action |
|---|---|---|
| Colonne Sondes vide (—) et Santé à « ? » | Mode Basic pur, aucun token configuré | Normal si voulu ; sinon ajouter un token Étendu ou Push (admin) |
| 🔴 Hors ligne (colonne Santé) | 2 sondes consécutives en échec sur /status.php |
2. Mode Basic |
| ⚡ Étendu orange + ⚠ | Token invalide (401/403) ou app serverinfo absente (404) | 3. Mode Étendu |
| ⚡ Étendu orange + 🕐 | Dernière collecte réussie il y a plus de 26h | 3. Mode Étendu |
| 📡 Push orange + ⚠ | Cron distant jamais exécuté, ou toujours en échec (token/URL) | 4. Mode Push |
| 📡 Push orange + 🕐 | Cron distant arrêté ou en échec depuis peu (dernier envoi trop ancien) | 4. Mode Push |
| 📡 Push + marqueur ↑ | Script distant plus ancien que la version courante (données OK par ailleurs) | 4. Mode Push |
| « Déclencher les Push » cliqué, rien ne change immédiatement | Comportement normal : le bouton pose un indicateur, l'envoi attend le prochain cron distant | Patienter un cycle cron puis rafraîchir |
| Message d'erreur en anglais lors d'un ajout/test de serveur | Blocage anti-SSRF volontaire (IP interne, localhost, identifiants dans l'URL…) | 7. Erreur vs blocage sécurité |
9. Rappel : où configurer un token
Chaque serveur a sa propre carte dans l'admin, avec deux zones indépendantes — token Serverinfo (lecture, Étendu) à gauche, token Push (écriture, script distant) à droite :
Pour les commandes exactes (générer/vérifier/supprimer un token, déployer ou mettre à jour le script Push), dépliez les sections « 🛠️ Sonde Étendue » et « 📡 Sonde Push » en haut de la page Admin.