Exit-Codes von ssh und scp: 255 ist der Fehler von ssh selbst, jeder andere Wert stammt vom Remote-Befehl

Worum es geht

Das OpenSSH-Handbuch sagt es unmissverständlich: "ssh exits with the exit status of the remote command or with 255 if an error occurred." Daraus folgt:

• Jeder Wert von 0 bis 254 stammt vom Befehl, der auf dem Remote-Host lief; ssh reicht ihn lediglich weiter.
• 255 bedeutet entweder, dass ssh selbst gescheitert ist (DNS-Fehler, Verbindung abgelehnt, Authentifizierungsfehler, abweichender Host-Key, Fehler auf Protokollebene), oder dass der Remote-Befehl durch ein Signal beendet wurde und somit kein Exit-Status zum Weiterreichen vorhanden ist (ein kill -9 auf dem Remote-Host erscheint als 255, nicht als 137).

Das Handbuch von scp ist deutlich weniger präzise: "The scp utility exits 0 on success, and >0 if an error occurs." Anders als die 255-Konvention von ssh trennt es lokale bzw. Transportfehler nicht von Remote-Fehlern. Aktuelles OpenSSH-scp (z. B. 9.6) beendet sich bei Dateifehlern mit 1 und mit 255, wenn die ssh-Verbindung scheitert, doch das Handbuch sichert dies nicht zu.

Warum es wichtig ist

Ein Skript, das ssh host some-command ausführt und nur $? -eq 0 prüft, kann nicht unterscheiden, ob der Remote-Befehl mit einem eigenen, aussagekräftigen Code fehlgeschlagen ist oder ob ssh den Host nie erreicht hat. Werden beide Fälle gleich behandelt, etwa durch blindes Wiederholen, wird ein Host, der Verbindungen schlicht ablehnt, mit Anfragen überhäuft, oder der echte Exit-Status 1, 2 oder 127 eines Remote-Befehls wird stillschweigend ignoriert.

So wird es angewendet

• Nach ssh host cmd zuerst auf 255 prüfen: Das ist als Problem der Konnektivität, der Authentifizierung oder des Host-Keys zu behandeln. Dazu die stderr-Ausgabe von ssh auswerten (ohne -q ausführen, da diese Option solche Diagnosemeldungen unterdrückt), statt den Fehlerraum des Remote-Befehls heranzuziehen.
• Jeder andere Wert ungleich 0 gehört zum eigenen Vertrag des Remote-Befehls; die Interpretation entspricht derjenigen beim lokalen Aufruf dieses Befehls (z. B. bedeutet 127 vermutlich "command not found" im PATH des Remote-Hosts, nicht des lokalen Rechners).
• Bei scp ist nur "0 gegenüber >0" dokumentiert. Die Fehlerklasse daher nicht aus der Zahl ableiten, sondern den stderr-Text von scp bzw. ssh auswerten. Alternativ auf sftp oder rsync -e ssh wechseln, wenn feiner abgestufte, dokumentierte Codes nötig sind.
• Beim Einsatz von timeout liegen dessen eigene Codes (124 bzw. 137 nach --kill-after) über der Konvention von ssh; diese zuerst prüfen, bevor der Rest interpretiert wird.

Stolpersteine

• Ein Remote-Befehl, der selbst mit 255 endet, ist allein anhand des Exit-Codes nicht von einem Fehler auf ssh-Ebene zu unterscheiden. Abhilfe schaffen die Fehlerausgabe von ssh auf stderr oder ein Remote-Befehl, der 255 vermeidet.
• Auch Fehler bei ProxyJump/ProxyCommand erscheinen als 255 von ssh und nicht als eigener Code; die Ursache kann also im Jump-Host liegen statt im eigentlichen Ziel.