🔧 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 (ou plus) de données : Basic (/status.php), Étendu (API serverinfo) ou Push (cron sur l'instance distante). En 3 temps : repérer le symptôme, comprendre la cause probable, puis tester sans NcStatusCheck pour confirmer avant de toucher à la configuration.
Les commandes pour configurer un token serverinfo ou déployer le script Push sont dans les sections « 🛠️ Sonde Étendue » et « 📡 Sonde Push » de la page Admin ; cette page y renvoie une fois la cause trouvée.
1. Repérer le symptôme : les icônes de sonde du tableau de bord
Dans le tableau de bord, les icônes ⚡ Étendu et 📡 Push sont à côté de l'adresse de chaque serveur. Discrètes quand tout va bien, elles portent un marqueur (⚠, 🕐 ou ↑) quand quelque chose ne remonte plus. Un serveur en mode Basic pur n'a aucune icône.
| Ce que vous voyez | Signification | Aller à |
|---|---|---|
| ⚡ | Sonde Étendue fonctionnelle, données à jour | — |
| ⚡ ⚠ | Erreur de connexion à l'API serverinfo (token, app non installée, réseau…) | 3. Mode Étendu |
| ⚡ 🕐 | Dernière collecte réussie il y a plus de 26h | 3. Mode Étendu |
| 📡 | Sonde Push fonctionnelle, données récentes | — |
| 📡 ⚠ | Aucune donnée jamais reçue de cette instance | 4. Mode Push |
| 📡 🕐 | Dernière réception plus ancienne que l'intervalle configuré (+ 30 min de grâce) | 4. Mode Push |
| 📡 ↑ | Le script installé sur l'instance est plus ancien que la version courante | 4. Mode Push |
| aucune icône | Mode Basic pur (aucun token) : normal, ce n'est pas une panne | 2. Mode Basic |
| 🔴 Hors ligne | Colonne Santé : le serveur ne répond plus depuis 2 sondes consécutives | 2. Mode Basic |
| ⚙️ Système | Colonne Santé : occ ne démarre plus sur l'instance ; les tâches de fond sont probablement arrêtées aussi |
4. Mode Push |
Pour ne garder que les serveurs concernés : filtre État général → Sonde en erreur du tableau de bord.
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 : Étendu et Push s'y replient en cas d'échec, donc un problème ici peut toucher les autres modes.
📄 Fichier concerné : en Basic pur, l'entrée du serveur dans servers.json (racine de NcStatusCheck) ne contient que l'URL : {"url": "https://votre-nextcloud.tld"}.
Étape 1 : tester depuis un poste quelconque, indépendamment de NcStatusCheck
Attendu : HTTP/1.1 200 et un JSON avec "installed":true et "versionstring":"…". Si cette commande échoue déjà depuis votre poste, le problème est côté Nextcloud (pare-feu, certificat expiré, service arrêté), pas dans NcStatusCheck.
Étape 2 : si le curl marche mais pas le monitoring
Le problème est alors propre à NcStatusCheck : IP du monitor bloquée par un pare-feu/WAF côté Nextcloud, DNS différent, ou refus anti-SSRF (voir §7). Le message exact est dans cache/monitor.log (voir §6) : lignes cURL error for … ou HTTP failure for … (code: …).
? gris dans la colonne Santé n'est pas une panne : il signale l'absence de sonde Étendue/Push. Le badge 🔴 Hors ligne vient d'un suivi à part (uptime_state.json) : le serveur passe « down » après 2 sondes consécutives en échec (par défaut) et redevient « up » dès la première sonde réussie.3. Mode Étendu (serverinfo) : icône ⚡ avec ⚠ ou 🕐
Interroge /ocs/v2.php/apps/serverinfo/api/v1/info avec l'en-tête NC-Token. Le champ extended_error n'est qu'un drapeau vrai/faux, sans le message d'erreur. Pour le motif exact : bouton « Tester » ou 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 manquante invalide tout le fichier), mais l'admin est plus sûre. Après un succès, la réponse est mise en cache dans cache/serverinfo_<md5(url)>.json ; supprimer ce fichier force une nouvelle collecte (md5 de l'URL exacte : 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 afficher au moins une version. Une version affichée ne prouve donc pas que la sonde marche : seule l'icône ⚡ (et son marqueur ⚠) fait foi.4. Mode Push : icône 📡 avec ⚠, 🕐 ou ↑
Le Push est piloté par un cron sur l'instance Nextcloud distante, pas par NcStatusCheck : une sonde Push en défaut signifie presque toujours que le script distant ne tourne plus ou échoue.
📄 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 :
Sur l'instance Nextcloud, tout est suffixé par un slug tiré de l'URL surveillée (affiché à la génération du script, ex. cloud.example.com → cloud_example_com) :
Le script /usr/local/bin/ncstatuscheck-push.sh est générique et partagé par toutes les instances de l'hôte (une seule copie à mettre à jour) ; seul le .conf change.
É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).
Le script refuse de démarrer (aucun envoi, aucun log)
Le script s'arrête avant tout envoi si ses fichiers de configuration ne sont pas sûrs : il les source en root et ils décident où partent les données. Vu du monitor, c'est indiscernable d'un cron arrêté : le message n'existe que sur l'instance (sortie du cron, ou lancement à la main).
| Message observé | Action |
|---|---|
… is group/world-writable — refusing to run |
Un autre utilisateur peut réécrire ce fichier : chmod 600 <fichier> |
… is owned by uid N — refusing to run |
Le fichier appartient à un tiers, qui peut donc le réécrire quel que soit son mode : chown root:root <fichier> |
Étape 2 : rejouer manuellement
--test vérifie la configuration sans rien pousser (curl/jq/md5sum, occ, fichier targets-<instance>.conf). Une fois corrigé, relancez sans --test pour un envoi immédiat.
| Résultat | 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 |
403 (réponse vide ou page HTML, pas du JSON) |
La requête n'atteint jamais l'application : le filtrage IP du serveur web la refuse avant. L'adresse de sortie de cette instance n'est pas (ou plus) dans les règles. | Onglet 🚦 Filtrage IP de l'admin, étape 5 : la commande de diagnostic confirme le blocage. Retrouvez l'adresse réelle dans le journal d'accès, puis régénérez et réappliquez les règles. |
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 setupchecks plante. cron.php démarre de la même façon : les tâches de fond sont donc probablement arrêtées. L'erreur exacte est sur la page détail, onglet Infos. Cause fréquente : une extension PHP (souvent redis) présente pour le web mais absente en ligne de commande. Vérifiez en lançant votre commande occ à la main sur l'instance (ex. sudo -u www-data php occ status).occ passe par docker exec : OCC_CMD=docker exec -u www-data <conteneur> php occ (AIO : nextcloud-aio-nextcloud). Deux pièges : jamais de -t (pas de TTY sous cron), et garder -u www-data (l'image officielle refuse occ en root). Test : docker exec -u www-data <conteneur> php occ status --output=json ; si du JSON sort, seul OCC_CMD est en cause.5. Tester à la main, indépendamment de NcStatusCheck
Avant de changer une configuration, isolez l'origine du problème : ces trois commandes se passent de NcStatusCheck et se lancent depuis n'importe quel poste ayant accès au Nextcloud (la dernière, en SSH sur l'instance).
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 … — … |
cache/alerts.log |
Alertes proactives envoyées (webhook, email) : OK/ERR par canal. Seul schéma://hôte du webhook est tracé, jamais l'URL complète |
[date] OK|ERR [canal] message |
cache/advisories.log |
Collecte des vulnérabilités connues (cron-advisories.php, 1×/jour) |
[date] [NIVEAU] [PID:n] message |
Les logs sont bornés à 5 Mo (rotation en .old, .1 pour alerts.log). Les identifiants présents dans une URL (user:pass@) sont toujours masqués avant écriture.
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, avec l'adresse source réelle et les monitors destinataires déclarés. Le 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 caches du monitor sont nommés d'après le md5 de l'URL exacte : 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 ?
À l'ajout ou au test d'un serveur, un message d'erreur en anglais brut (les autres sont traduits) signale un refus volontaire de NcStatusCheck, pas un problème réseau 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 |
response over 2 MB — refused |
Le serveur surveillé a renvoyé plus de 2 Mo sur /status.php ou l'API serverinfo. La réponse est coupée exprès : sans plafond, un serveur qui gave sa réponse épuiserait la mémoire de PHP et arrêterait la collecte de tous les serveurs. Une réponse normale pèse quelques Ko : c'est le signe d'un proxy ou d'une page d'erreur mal configurés. |
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 redirection vers une IP interne est bloquée en cours de requête). C'est voulu (anti-SSRF) : rien à réparer côté Nextcloud, l'URL doit simplement être une adresse publique valide.
8. Tableau récapitulatif : symptôme → cause probable → action
| Symptôme | Cause probable | Action |
|---|---|---|
| Aucune icône de sonde 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 |
| ⚡ + ⚠ | Token invalide (401/403) ou app serverinfo absente (404) | 3. Mode Étendu |
| ⚡ + 🕐 | Dernière collecte réussie il y a plus de 26h | 3. Mode Étendu |
| 📡 + ⚠ | Cron distant jamais exécuté, ou toujours en échec (token/URL) | 4. Mode Push |
| 📡 + 🕐 | Cron distant arrêté ou en échec depuis peu (dernier envoi trop ancien) | 4. Mode Push |
| 📡 + ↑ | 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é |
| ⚙️ Système (colonne Santé) | occ plante sur l'instance : cron.php probablement arrêté aussi | 4. Mode Push |
9. Rappel : où configurer un token
Chaque serveur a sa propre carte dans l'admin. Le bouton ⚙ Configurer les sondes déplie deux zones indépendantes : token Serverinfo (lecture, Étendu) à gauche, token Push (écriture, script distant) à droite :
Pour les commandes exactes (token, déploiement ou mise à jour du script Push), dépliez « 🛠️ Sonde Étendue » et « 📡 Sonde Push » en haut de la page Admin.