Codes de sortie de ssh et scp : 255 signale un échec de ssh lui-même, tout autre code vient de la commande distante

Ce que c'est

Le manuel d'OpenSSH l'énonce clairement : « ssh exits with the exit status of the remote command or with 255 if an error occurred. » Concrètement :

• Toute valeur comprise entre 0 et 254 provient de la commande exécutée sur l'hôte distant ; ssh se contente de la relayer.
• 255 signifie soit que ssh lui-même a échoué (échec DNS, connexion refusée, échec d'authentification, clé d'hôte non concordante, erreur au niveau du protocole), soit que la commande distante a été tuée par un signal, de sorte qu'aucun code de sortie n'est disponible à relayer (un kill -9 distant apparaît sous la forme 255, et non 137).

Le manuel de scp est bien moins précis : « The scp utility exits 0 on success, and >0 if an error occurs. » Il ne sépare pas un échec local ou de transport d'un échec distant, comme le fait la convention 255 de ssh. Le scp d'OpenSSH actuel (par exemple 9.6) renvoie 1 pour les erreurs de fichier et 255 lorsque la connexion ssh échoue, mais le manuel ne le garantit pas.

Pourquoi c'est important

Un script qui exécute ssh host some-command et ne vérifie que $? -eq 0 ne peut pas distinguer « la commande distante a échoué avec son propre code, porteur de sens » de « ssh n'a jamais atteint l'hôte ». Réagir de la même manière dans les deux cas, par exemple en relançant aveuglément, revient à harceler un hôte qui refuse simplement les connexions, ou à ignorer silencieusement le véritable code de sortie 1, 2 ou 127 d'une commande distante.

Comment l'appliquer

• Après ssh host cmd, testez d'abord la valeur 255 : traitez-la comme un problème de connectivité, d'authentification ou de clé d'hôte, et examinez la sortie d'erreur de ssh (exécutez sans -q, qui supprime ces diagnostics) plutôt que l'espace d'erreurs propre à la commande distante.
• Tout autre code non nul relève du contrat de la commande distante : appliquez le même raisonnement que si vous l'exécutiez localement (par exemple, 127 signifie probablement « commande introuvable » dans le PATH de l'hôte distant, et non dans celui de la machine locale).
• Pour scp, comme seule la distinction « 0 ou >0 » est documentée, n'essayez pas de déduire la nature de l'échec à partir du nombre ; analysez le texte de la sortie d'erreur de scp ou de ssh, ou passez à sftp ou à rsync -e ssh si vous avez besoin de codes plus fins et documentés.
• Si vous encapsulez l'appel dans timeout, ses propres codes (124, ou 137 après --kill-after) se superposent à la convention de ssh : vérifiez-les avant d'interpréter le reste.

Pièges

• Une commande distante qui se termine elle-même avec le code 255 est indiscernable, par le seul code de sortie, d'un échec au niveau de ssh ; levez l'ambiguïté grâce au message d'erreur de ssh sur stderr, ou faites en sorte que la commande distante évite 255.
• Les échecs de ProxyJump ou de ProxyCommand se manifestent eux aussi par le code 255 de ssh, et non par un code distinct : la panne peut se situer sur l'hôte de rebond plutôt que sur la cible finale.