Códigos de salida de ssh y scp: 255 es un fallo del propio ssh; cualquier otro valor es del comando remoto

Qué es

El manual de OpenSSH lo expresa con claridad: "ssh exits with the exit status of the remote command or with 255 if an error occurred." Esto significa que:

• Cualquier valor entre 0 y 254 procede del comando ejecutado en el host remoto; ssh se limita a retransmitirlo.
• 255 indica que falló el propio ssh (fallo de DNS, conexión rechazada, fallo de autenticación, host key no coincidente, error a nivel de protocolo) o que el comando remoto fue terminado por una señal y no hay ningún código de salida que retransmitir (un kill -9 remoto aparece como 255, no como 137).

El manual de scp es mucho menos específico: "The scp utility exits 0 on success, and >0 if an error occurs." No distingue un fallo local o de transporte de uno remoto como lo hace la convención del 255 en ssh. El scp actual de OpenSSH (por ejemplo, 9.6) devuelve 1 para errores de archivo y 255 cuando falla la conexión ssh, pero el manual no lo garantiza.

Por qué importa

Un script que ejecuta ssh host some-command y solo comprueba $? -eq 0 no puede distinguir entre "el comando remoto falló con su propio código significativo" y "ssh nunca llegó al host". Si se reacciona igual ante ambos casos (por ejemplo, reintentando a ciegas), se acabará saturando de intentos un host que simplemente rechaza conexiones, o se ignorará en silencio el código de salida real (1, 2, 127) del comando remoto.

Cómo aplicarlo

• Tras ssh host cmd, comprueba primero si el código es 255: trátalo como un problema de conectividad, autenticación o host key e inspecciona el stderr de ssh (ejecútalo sin -q, que suprime esos diagnósticos) en lugar de buscar en el espacio de errores del comando remoto.
• Cualquier otro código distinto de cero pertenece al contrato del propio comando remoto: aplica el mismo razonamiento que usarías si ejecutaras ese comando en local (por ejemplo, 127 probablemente significa "comando no encontrado" en el PATH del host remoto, no en el local).
• En scp, como solo se documenta "0 frente a >0", no intentes deducir la clase de fallo a partir del número; analiza el texto de stderr de scp o de ssh, o cambia a sftp/rsync -e ssh si necesitas códigos documentados de mayor granularidad.
• Si envuelves la llamada con timeout, sus propios códigos (124, o 137 tras --kill-after) se superponen a la convención de ssh: compruébalos antes de interpretar el resto.

Trampas

• Un comando remoto que por casualidad termine con 255 no se distingue, solo por el código de salida, de un fallo a nivel de ssh; para desambiguar, usa el banner de stderr de ssh o haz que el comando remoto evite el 255.
• Los fallos de ProxyJump/ProxyCommand también aparecen como el 255 propio de ssh, sin un código distinto: el fallo puede estar en el host intermedio y no en el destino final.