Códigos de saída de ssh e scp: 255 é falha do próprio ssh, qualquer outro valor vem do comando remoto

O que é

O manual do OpenSSH diz isso de forma direta: "ssh exits with the exit status of the remote command or with 255 if an error occurred." Isso significa:

• Qualquer valor de 0 a 254 veio do comando executado no host remoto; o ssh apenas o repassa.
• 255 significa que o próprio ssh falhou (falha de DNS, conexão recusada, falha de autenticação, host key divergente, erro de nível de protocolo) ou que o comando remoto foi morto por um sinal, de modo que não existe código de saída para repassar (um kill -9 remoto aparece como 255, não como 137).

O manual do scp é bem menos específico: "The scp utility exits 0 on success, and >0 if an error occurs." Ele não separa uma falha local ou de transporte de uma falha remota, como a convenção do 255 no ssh faz. O scp atual do OpenSSH (por exemplo, 9.6) sai com 1 para erros de arquivo e com 255 quando a conexão ssh falha, mas o manual não garante esse comportamento.

Por que importa

Um script que executa ssh host some-command e verifica apenas $? -eq 0 não consegue distinguir "o comando remoto falhou com um código próprio e significativo" de "o ssh nunca chegou ao host". Tratar os dois casos da mesma forma, por exemplo com novas tentativas às cegas, sobrecarrega um host que simplesmente está recusando conexões, ou ignora em silêncio o código de saída real 1/2/127 de um comando remoto.

Como aplicar

• Depois de ssh host cmd, verifique primeiro se o código é 255: trate-o como problema de conectividade, autenticação ou host key e inspecione o stderr do ssh (execute sem -q, que suprime esses diagnósticos), em vez de olhar o espaço de erros do próprio comando remoto.
• Qualquer outro código diferente de zero pertence ao contrato do comando remoto: raciocine como faria ao executar esse comando localmente (por exemplo, 127 provavelmente significa "command not found" no PATH do host remoto, não no local).
• Para o scp, como só "0 contra >0" está documentado, não tente inferir a classe da falha pelo número; analise o texto de stderr do scp/ssh ou mude para sftp/rsync -e ssh se precisar de códigos documentados e mais detalhados.
• Ao envolver o comando em timeout, os códigos dele (124, ou 137 após --kill-after) se sobrepõem à convenção do ssh; verifique-os antes de interpretar o restante.

Armadilhas

• Um comando remoto que por acaso termina com 255 não pode ser distinguido de uma falha no nível do ssh apenas pelo código de saída; desambigue usando o banner de stderr do ssh ou fazendo o comando remoto evitar o 255.
• Falhas de ProxyJump/ProxyCommand também aparecem como o 255 do próprio ssh, e não como um código distinto: a falha pode estar no jump host, e não no destino final.