Vérifier la réussite d'une commande SSH : prouver que le travail distant est terminé

Une commande SSH qui se termine avec le statut 0 n'a accompli qu'une tâche limitée : le programme distant a indiqué à son shell qu'il avait réussi. C'est un indice utile, mais ce n'est pas la preuve qu'un déploiement a atteint la bonne version, qu'un service est resté sain ou qu'une modification de configuration a bien été appliquée.

J'ai souvent vu des automatisations crier victoire parce que ssh host command renvoyait zéro, avant de découvrir que la commande avait écrit dans le mauvais répertoire, placé un travail en file d'attente qui avait échoué plus tard ou redémarré un service qui s'était immédiatement arrêté. La solution ne consiste pas à ajouter des journaux plus optimistes. Considérez une modification distante comme terminée seulement lorsque trois faits distincts concordent : SSH a atteint le programme distant, le programme a renvoyé le résultat attendu et une lecture indépendante confirme l'état que vous vouliez créer.

Un code de sortie SSH ne décrit qu'un niveau de l'opération

Un statut de sortie renseigne sur la fin d'un processus, pas sur le résultat opérationnel complet. Une commande distante repose sur plusieurs hypothèses : résolution DNS et connectivité réseau, identité de l'hôte, authentification, comportement du shell, interprétation de la commande, dépendances, permissions distantes et état que vous espériez modifier.

Le manuel OpenSSH ssh(1) indique que ssh se termine avec le statut de la commande distante, ou avec 255 lorsqu'une erreur survient. Cette distinction compte. Le statut 255 signifie généralement que le client SSH n'a pas pu établir ou maintenir la session comme prévu. Un statut égal à 1, 2 ou à une autre valeur non nulle provient normalement de la commande distante. Le zéro provient lui aussi de cette commande.

Cette formulation ne signifie pas que zéro veut dire « la modification de production est correcte ». SSH ne peut pas le savoir. Il ignore si /srv/app/current pointe vers la version voulue, si un démon accepte les requêtes après systemctl restart ou si une migration de base de données a bien validé les lignes nécessaires à l'application.

POSIX définit le statut de sortie zéro comme une exécution réussie d'une commande. L'intérêt de cette définition tient à sa portée limitée. Elle décrit le contrat de la commande. Si votre contrat se résume à « exécuter cette ligne shell », le zéro ne prouve presque rien. Donnez à la commande un contrat plus précis, puis testez l'état en dehors de cette commande.

Une manière pratique de réfléchir aux échecs consiste à les séparer en trois niveaux :

• Échec SSH : le client n'a pas pu se connecter, s'authentifier, vérifier l'hôte ou terminer la session.
• Échec de la commande : le processus distant a détecté une erreur et renvoyé un statut non nul.
• Échec du résultat : le processus a renvoyé zéro, mais l'état distant voulu est absent, incorrect, incomplet ou a ensuite été annulé.

Les équipes confondent souvent les deux derniers niveaux. Les comptes rendus d'incident deviennent alors vagues et les relances dangereuses. Si vous savez quel niveau a échoué, vous saurez s'il faut examiner les identifiants et la connectivité, corriger la commande ou réparer l'état distant.

Un texte de réussite n'est une preuve que si vous le définissez précisément

Les vérifications de sortie détectent des erreurs que le statut de sortie ne voit pas, mais seulement si la sortie possède un contrat explicite. Rechercher des mots comme success, complete ou deployed dans une transcription destinée à un humain fournit une preuve faible. De nombreux outils affichent ces mots avant l'échec d'une commande ultérieure, et les wrappers les affichent parfois après avoir seulement soumis un travail asynchrone.

Faites émettre à la commande distante un enregistrement unique contenant l'identité et l'état attendus. JSON est souvent pratique, mais une ligne à séparateurs fixes convient si vous contrôlez les valeurs. L'essentiel est que le script n'affiche l'enregistrement qu'après avoir effectué le travail qu'il prétend décrire.

Par exemple, supposons qu'un script de mise en production bascule un lien symbolique vers un répertoire de version. Ce script distant émet la cible finale, plutôt qu'un vague message de progression :

#!/bin/sh
set -eu

release="$1"
base=/srv/example/releases
link=/srv/example/current

[ -d "$base/$release" ]
ln -sfn "$base/$release" "$link"

actual=$(readlink "$link")
[ "$actual" = "$base/$release" ]
printf 'RELEASE_TARGET=%s\n' "$actual"

L'appelant peut exiger une ligne de sortie exacte :

expected="RELEASE_TARGET=/srv/example/releases/2025.06.14"
output=$(ssh deploy@web-01 '/usr/local/sbin/activate-release 2025.06.14' 2>&1)
status=$?

if [ "$status" -ne 0 ]; then
  printf 'remote command failed, status=%s\n%s\n' "$status" "$output" >&2
  exit "$status"
fi

if ! printf '%s\n' "$output" | grep -Fxq "$expected"; then
  printf 'remote command returned unexpected output:\n%s\n' "$output" >&2
  exit 1
fi

grep -Fxq est important ici. Il vérifie une ligne complète et fixe. Une expression vague comme grep deployed accepte les éléments parasites, les correspondances partielles et les journaux de progression trompeurs. Si la sortie contient des champs dynamiques, analysez un document structuré avec un véritable analyseur plutôt que d'essayer de faire comprendre des données imbriquées à une expression régulière.

Ne transformez pas la comparaison de sortie en copie intégrale de la commande. Elle doit répondre à une seule question : le programme distant a-t-il indiqué qu'il avait atteint l'état nommé ? La lecture de suivi permet de vérifier si cette affirmation reste vraie là où cela compte.

Les écritures distantes ont besoin d'une lecture effectuée par le propriétaire de l'état

Une lecture de suivi fournit la confirmation la plus solide, car elle interroge le composant qui possède l'état modifié. La bonne lecture dépend de la modification et diffère souvent de la commande qui l'a effectuée.

Pour un changement de lien symbolique, readlink vérifie le système de fichiers. Pour le déploiement d'un paquet, interrogez la version installée. Après le redémarrage d'un service, demandez au gestionnaire de services son état actif, puis envoyez une requête au service. Pour une modification de base de données, lisez la ligne concernée ou utilisez le point d'état prévu par l'application. Pour une tâche en file d'attente, interrogez l'enregistrement de la tâche jusqu'à ce qu'il atteigne un état terminal.

Le mauvais schéma ressemble à ceci :

ssh deploy@web-01 'deploy-release 2025.06.14 && systemctl restart example'

La commande peut renvoyer zéro alors que le service est « actif », mais utilise une ancienne version parce que le script de déploiement a écrit dans un autre chemin. Elle peut aussi renvoyer zéro lorsque le gestionnaire accepte le redémarrage, puis que le processus meurt quelques instants plus tard. Le shell a vu deux programmes renvoyer zéro. Les utilisateurs obtiennent malgré tout un service défaillant.

Utilisez une lecture qui rend la condition souhaitée observable. Un contrôle de déploiement peut ressembler à ceci :

ssh deploy@web-01 '
  test "$(readlink /srv/example/current)" = /srv/example/releases/2025.06.14 &&
  systemctl is-active --quiet example &&
  curl --fail --silent --show-error http://127.0.0.1:8080/healthz
'

Cette version est meilleure, car elle vérifie trois affirmations que la commande originale supposait seulement. Elle ne prouve pas pour autant que tous les utilisateurs externes peuvent atteindre le service. Si la modification concerne un point d'accès public, effectuez un contrôle adapté depuis la position réseau réelle des utilisateurs. Un contrôle local sur loopback détecte un échec du processus, pas une erreur de pare-feu ou d'équilibreur de charge.

Les contrôles de lecture après écriture doivent, si possible, emprunter un chemin indépendant. Exécuter une seconde fonction dans le même script de déploiement vaut mieux que rien, mais cette fonction peut partager la même variable erronée, le mauvais hôte ou la même dépendance simulée. Une commande distincte qui interroge le système de fichiers, le gestionnaire de services, l'API ou la base de données réduit ce risque commun.

Une commande doit indiquer si elle est synchrone

De nombreuses commandes distantes renvoient zéro parce qu'elles ont accepté un travail, et non parce que ce travail est terminé. C'est un résultat correct pour une soumission en file d'attente, une tâche d'arrière-plan, une demande de rechargement de service ou une API d'orchestration. Cela devient un problème lorsque l'appelant confond acceptation et achèvement.

Distinguez les deux contrats dans les noms et dans la sortie. submit-backup peut renvoyer un identifiant de tâche et zéro lorsque le serveur a accepté la demande. wait-backup ne doit renvoyer zéro qu'après le signalement de la fin de cette tâche précise. N'appelez pas les deux actions backup en espérant que l'opérateur se souviendra de la version exécutée sur chaque hôte.

Un script distant qui lance un travail en arrière-plan demande une attention particulière. Cette ligne shell renvoie un succès après avoir lancé un processus, même si celui-ci échoue immédiatement :

long-task >/var/log/long-task.log 2>&1 &
printf 'started\n'

Le code de sortie ultérieur du processus n'est pas accessible à l'appelant SSH. Enregistrez-le dans un emplacement durable et interrogez-le plus tard, ou gardez la session ouverte jusqu'à ce que la tâche atteigne un état significatif. Si vous détachez la tâche, écrivez un identifiant d'opération dans un fichier ou une base de données et renvoyez cet identifiant. L'appelant pourra ensuite interroger l'enregistrement ou attendre son évolution.

Un enregistrement de fin utile contient assez d'informations pour rapprocher le travail :

operation=4f2c1a status=accepted release=2025.06.14

L'appelant ne doit pas considérer cet enregistrement comme un déploiement terminé. Il doit interroger operation=4f2c1a et exiger un état terminal tel que completed, ainsi qu'une vérification de l'état produit. Cela peut sembler excessif pour un script simple. C'est bien moins contraignant que de deviner s'il est possible de relancer le script sans danger après un délai d'attente.

Les délais d'attente demandent la même distinction. Un délai local indique que l'appelant a cessé d'attendre. Il ne dit pas que la commande distante s'est arrêtée. Le réseau a pu tomber après la validation d'une modification par l'hôte distant. Avant de relancer, inspectez l'état distant ou interrogez l'identifiant d'opération. Relancer l'activation d'une version peut être sans danger si l'opération est idempotente. Relancer un paiement, une rotation de secret ou un envoi d'e-mail peut aggraver les conséquences.

La composition shell masque les échecs si vous ne l'écrivez pas pour les révéler

La syntaxe du shell distant peut transformer un échec réel en statut final réussi. C'est l'une des plus anciennes raisons pour lesquelles une exécution SSH semble propre alors qu'elle laisse une machine endommagée.

Considérez cette commande :

ssh ops@db-01 'backup-db; upload-backup; prune-old-backups'

Le shell distant renvoie le statut de prune-old-backups, sa dernière commande. Si la sauvegarde échoue mais que le nettoyage réussit, la commande SSH globale renvoie zéro. La transcription peut contenir une erreur au début, tandis qu'un pipeline qui ne lit que le statut marque l'exécution comme réussie.

Utilisez set -e dans un script que vous contrôlez, ou reliez les commandes dépendantes avec && lorsqu'une commande compacte reste lisible :

ssh ops@db-01 'backup-db && upload-backup && prune-old-backups'

set -e n'est pas magique. Les shells prévoient des exceptions autour des conditionnelles, des substitutions de commande et de certaines constructions composées. N'écrivez pas une longue commande distante sur une seule ligne en supposant qu'une option rendra toutes les erreurs visibles. Placez le travail non trivial dans un script distant, donnez à chaque opération une condition de réussite claire et testez son comportement en cas d'échec.

Les pipelines introduisent un autre piège courant. Dans de nombreux shells POSIX, ceci réussit si le dernier programme réussit, même si le producteur précédent échoue :

collect-metrics | format-report > /var/tmp/report.txt

Certains shells proposent set -o pipefail, mais /bin/sh peut ne pas le prendre en charge. Si l'environnement distant doit rester portable avec POSIX, n'utilisez pas un pipeline comme seule limite d'erreur. Écrivez les données intermédiaires dans un fichier temporaire, vérifiez le statut du producteur, puis consommez-les. Vous pouvez aussi exécuter le script avec un shell dont vous exigez explicitement le comportement pipefail.

Évitez également de terminer une commande distante par une sortie de diagnostic susceptible de réussir après l'échec du vrai travail :

apply-config
printf 'finished\n'

Sans set -e ni vérification explicite, printf devient le statut de sortie. Cette erreur apparaît dans les commandes d'incident écrites à la main parce que quelqu'un veut afficher un message final convivial. N'affichez ce message qu'après une vérification de condition, ou laissez la commande échouée arrêter le script.

Les erreurs de guillemets peuvent vous faire vérifier la mauvaise machine

Un shell local développe les variables non protégées avant qu'SSH n'envoie la commande. Une commande peut ainsi s'exécuter avec la mauvaise version, comparer la sortie locale plutôt que la sortie distante ou exposer des valeurs dans la liste des processus et les journaux.

Cette commande est incorrecte si vous voulez que l'hôte distant évalue $release :

ssh deploy@web-01 "test \"$(readlink /srv/example/current)\" = \"$release\""

Le shell local évalue $(readlink ...) avant de lancer SSH. Vous avez comparé le /srv/example/current de votre poste, s'il existe, à une variable locale, puis envoyé le texte obtenu au shell distant. Le statut peut être égal à zéro. Le contrôle n'a pas inspecté l'hôte cible.

Gardez le programme distant entre apostrophes lorsqu'il contient une syntaxe shell qui doit être exécutée à distance. Transmettez les valeurs non fiables ou dynamiques comme paramètres positionnels plutôt que de construire du texte shell. Par exemple :

release='2025.06.14'
ssh deploy@web-01 'sh -s -- "$1"' sh "$release" <<'REMOTE'
set -eu
release=$1
target=$(readlink /srv/example/current)
[ "$target" = "/srv/example/releases/$release" ]
printf 'verified=%s\n' "$target"
REMOTE

Le délimiteur de heredoc entre apostrophes empêche le shell local de développer le corps du script. La version circule comme argument shell, où le shell distant peut la protéger correctement. Cela ne rend pas automatiquement sûr un nom de version arbitraire. Validez les caractères et les formats autorisés avant d'utiliser des valeurs contrôlées par l'utilisateur dans des chemins, des commandes ou des requêtes de base de données.

Pour l'automatisation, préférez un script distant avec des paramètres à une chaîne toujours plus longue de guillemets imbriqués. Les erreurs de protection sont difficiles à repérer en revue de code, car la commande peut sembler plausible au premier regard. Elles deviennent beaucoup plus faciles à diagnostiquer lorsque les journaux indiquent la version exacte du script distant, les paramètres qu'il est possible de consigner sans risque et la sortie de la commande de vérification.

Un contrat SSH utile possède trois résultats distincts

Traitez chaque action SSH importante comme un petit protocole avec des champs séparés pour le transport, le résultat de la commande et l'état observé. L'appelant a besoin des trois pour décider s'il peut continuer, relancer ou demander de l'aide.

Cette fonction Bash montre la structure. Elle capture stderr avec stdout afin qu'une opération échouée laisse des éléments de diagnostic, tout en signalant séparément une erreur de transport SSH et une réponse de réussite inattendue.

run_remote_check() {
  local host=$1
  local expected=$2
  shift 2

  local output status
  output=$(ssh "$host" "$@" 2>&1)
  status=$?

  if [ "$status" -eq 255 ]; then
    printf 'ssh_transport=failed host=%s\n%s\n' "$host" "$output" >&2
    return 255
  fi

  if [ "$status" -ne 0 ]; then
    printf 'remote_command=failed host=%s status=%s\n%s\n' \
      "$host" "$status" "$output" >&2
    return "$status"
  fi

  if ! printf '%s\n' "$output" | grep -Fxq "$expected"; then
    printf 'remote_result=unexpected host=%s expected=%s\n%s\n' \
      "$host" "$expected" "$output" >&2
    return 1
  fi

  printf 'remote_result=confirmed host=%s\n' "$host"
}

Appelez-la avec une commande qui n'émet qu'un enregistrement contractuel après ses propres contrôles internes :

run_remote_check \
  deploy@web-01 \
  'RELEASE_TARGET=/srv/example/releases/2025.06.14' \
  '/usr/local/sbin/activate-release 2025.06.14'

Exécutez ensuite une lecture de suivi comme action distincte. Gardez-la séparée dans les journaux et dans le compte rendu des statuts. Si l'activation réussit mais que le contrôle du service échoue, les opérateurs doivent voir cette limite précise. Un résultat opaque comme deploy failed les oblige à relancer des commandes uniquement pour découvrir ce qui s'est déjà produit.

Pour les commandes qui renvoient des données structurées, renvoyez un petit objet JSON et analysez-le avec un analyseur JSON. N'utilisez pas grep sur du JSON, sauf si la sortie est volontairement un sentinelle sur une ligne et que vous n'avez pas besoin d'interpréter ses champs. La comparaison de chaînes sur du JSON arbitraire se casse lorsque les espaces, l'ordre ou les caractères échappés changent.

Le contrat doit aussi nommer l'objet cible. status=ok seul ne distingue pas la version 2025.06.14 de celle d'hier. Incluez l'identifiant du déploiement, le nom d'hôte lorsque c'est pertinent, la version de l'objet ou l'identifiant d'opération. Ce petit détail évite un faux positif étonnamment fréquent : le contrôle vérifie qu'un élément sain existe, mais pas qu'il s'agit de celui que l'exécution vient de modifier.

La visibilité doit conserver le résultat de la vérification

Un journal qui enregistre uniquement la commande distante et son statut laisse sans réponse la question la plus importante : l'appelant a-t-il observé indépendamment l'état attendu ? Enregistrez l'action de vérification et son résultat à côté de la modification.

Pour un déploiement, un enregistrement utile peut inclure l'hôte cible, l'identifiant de version, le statut SSH, le statut de la commande, l'enregistrement contractuel exact, le statut de la commande de suivi et un bref résultat de la lecture de santé ou d'état. Ne consignez pas les secrets, les en-têtes d'autorisation complets ni les arguments privés simplement parce qu'ils facilitent le diagnostic. Concevez l'interface de la commande afin que les preuves utiles puissent être conservées sans danger.

Sallyport conserve un journal d'activité pour les actions individuelles et un journal des sessions pour les exécutions d'agents, tous deux produits à partir d'un journal d'audit chiffré et chaîné par hachage. L'opérateur peut ainsi distinguer une action SSH exécutée d'une action de vérification ayant confirmé un résultat, au lieu de considérer un seul appel réussi comme toute l'histoire.

La preuve d'altération aide à déterminer si une action enregistrée a été modifiée après coup. Elle ne transforme pas un contrat de commande faible en preuve d'un bon résultat. sp audit verify peut vérifier hors ligne la chaîne du journal sur le texte chiffré, mais la conception de l'action a toujours besoin d'une lecture de suivi explicite.

Gardez la vérification suffisamment proche de l'écriture pour qu'un autre acteur ne puisse pas remplacer silencieusement l'état attendu pendant l'intervalle. Il n'est pas toujours possible d'éliminer les courses sur un système partagé. Vous pouvez les réduire avec des identifiants de version immuables, des identifiants d'opération, des contrôles de version et des API prenant en charge les mises à jour conditionnelles. Si l'état peut changer de nouveau, enregistrez la version ou l'heure observée et faites-la vérifier par l'automatisation suivante avant toute action.

Les relances exigent un rapprochement avant la répétition

Un délai d'attente, une connexion interrompue ou une tâche CI arrêtée créent un résultat inconnu. L'hôte distant peut avoir terminé la modification, être encore en train de l'exécuter ou avoir échoué en cours de route. L'appelant ne le sait pas simplement parce qu'il ne reçoit plus de sortie.

Ne résolvez pas cette incertitude par une relance aveugle. Exécutez d'abord une commande de rapprochement en lecture seule qui classe l'état distant. Pour une activation de version, inspectez le lien symbolique courant et la santé du service. Pour une migration, interrogez une table de migrations. Pour une ressource créée, interrogez-la avec un identifiant d'opération généré par l'appelant. Pour une rotation de secret, vérifiez quelle version les consommateurs utilisent réellement avant d'en générer une autre.

Une bonne commande de rapprochement renvoie un petit nombre de résultats explicites :

• completed : l'état cible correspond à l'opération demandée.
• running : l'opération possède encore du travail et l'appelant doit attendre.
• absent : aucune preuve de l'opération n'existe, une relance peut donc être appropriée.
• conflict : un état différent existe et un humain ou un contrôleur de niveau supérieur doit décider.

Ne forcez pas chaque résultat dans la réussite ou l'échec. running et conflict sont des résultats utiles. Un système qui les considère comme des échecs relance souvent un travail qu'il aurait fallu laisser en place.

L'idempotence réduit le coût des relances légitimes, mais ce mot est souvent mal employé. Une commande est idempotente lorsque la répétition de la même requête laisse l'état souhaité inchangé après la première application réussie. ln -sfn peut être idempotent pour une cible de lien donnée. « Créer une nouvelle sauvegarde avec l'heure courante » ne l'est pas. « Envoyer un e-mail » ne l'est pas non plus, sauf si le système en aval déduplique les messages à l'aide d'un identifiant stable.

Construisez la vérification de lecture avant d'ajouter les relances. Si vous ne pouvez pas expliquer comment identifier une opération terminée, vous ne pouvez pas automatiser sans danger la répétition après une incertitude. C'est à ce moment que l'automatisation SSH cesse d'être une simple commodité shell et commence à nécessiter un modèle d'opération.

La première correction consiste à auditer vos exécutions vertes

Commencez par les commandes distantes qui modifient l'état de production et ne signalent actuellement qu'un code de sortie vert. Pour chacune, notez l'objet distant qui doit changer, l'état exact qui compte comme réussite, le composant capable de lire cet état et ce qu'un délai d'attente laisse inconnu.

Modifiez ensuite l'interface de la commande afin qu'elle émette un enregistrement de résultat exact après ses propres contrôles. Ajoutez une action de lecture séparée. Conservez les deux résultats dans l'enregistrement d'exécution. Vous trouverez des commandes qui n'ont jamais été synchrones, des scripts dont le dernier printf masquait un échec antérieur et des contrôles de déploiement qui interrogeaient la machine ayant lancé la commande plutôt que celle qui l'avait reçue.

Un statut de sortie égal à zéro a toujours son utilité. C'est le premier filtre, pas le verdict final. Le traiter ainsi produit une automatisation capable d'expliquer ce qui s'est passé lorsque le signal vert, pourtant simple, s'avère incorrect.