WardtermClient SSH
FR
Télécharger

Le fichier de configuration SSH, avec des exemples

~/.ssh/config stocke des réglages par hôte : ssh web peut ainsi remplacer une longue commande. ssh lit le fichier de haut en bas, et la première valeur trouvée pour chaque option l'emporte : placez donc les hôtes précis en premier et les valeurs par défaut de Host * en dernier. Lancez ssh -G web pour voir les réglages finaux sans vous connecter.

Mis à jour le . Chaque exemple a été passé dans ssh -G avec OpenSSH 10.0 sur Debian 13, avec un vrai ~/.ssh/config dans un conteneur de test.

Un exemple qui fonctionne

Include ~/.ssh/config.d/*

Host web
  HostName 203.0.113.10
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Host *.example.com
  User admin

Host *
  ServerAliveInterval 60
  User user

Désormais, ssh web équivaut à ssh -p 2222 -i ~/.ssh/id_ed25519_work deploy@203.0.113.10, et envoie aussi un keepalive toutes les 60 secondes. Les mêmes noms fonctionnent pour scp, sftp et rsync.

Le fichier est ~/.ssh/config. Il ne doit pas être modifiable par d'autres, sinon ssh s'arrête avec Bad owner or permissions. Lancez chmod 600 ~/.ssh/config. Les réglages à l'échelle du système sont lus après lui, depuis /etc/ssh/ssh_config.

Avec des dizaines d'hôtes, le fichier ne suffit pas. Voyez comment gérer de nombreux serveurs SSH pour garder noms, groupes et clés en ordre.

La première valeur l'emporte

C'est la règle qui surprend. Chaque bloc Host qui correspond s'applique, pas seulement le premier. Pour chaque option, ssh garde la première valeur lue et ignore les suivantes. Dans l'exemple :

  • ssh web obtient User deploy, car son bloc vient avant Host *.
  • ssh db.example.com obtient User admin.
  • ssh other obtient User user, et les trois obtiennent ServerAliveInterval 60.

Placez donc les hôtes précis en haut et les valeurs par défaut à la fin. Si vous déplacez Host * en haut, son User l'emporte partout. Les options de la ligne de commande passent avant tout le reste : ssh -l other web, ssh other@web et ssh -p 3000 web écrasent donc le fichier.

Il y a une exception à connaître. IdentityFile s'additionne : une valeur dans Host web-* et une autre dans Host * sont toutes deux essayées, dans l'ordre. Ajoutez IdentitiesOnly yes si vous voulez éviter les clés de l'agent, et laissez IdentityFile hors de Host * si vous voulez une clé par hôte.

Motifs Host

MotifCorrespond à
Host web dbL'un ou l'autre nom.
Host *.example.comTout nom se terminant par .example.com.
Host web-?web- suivi d'un caractère.
Host web-* !web-oldTous les noms en web- sauf web-old. Une négation seule ne correspond à rien : elle ne fait qu'exclure d'une correspondance positive.

Le motif est comparé à ce que vous tapez, pas à l'adresse obtenue après résolution. %h représente ce nom, ce qui permet les noms courts :

Host web-*
  HostName %h.example.com

ssh web-1 se connecte désormais à web-1.example.com.

Include

Include ~/.ssh/config.d/*

Cela lit d'autres fichiers comme s'ils étaient collés à cet endroit, ce qui permet de garder un fichier par projet. Les chemins relatifs partent de ~/.ssh. Il faut OpenSSH 7.3 ou plus récent.

Placez-le en haut du fichier. Un bloc Host se poursuit jusqu'au suivant, et un Include placé après lui fait partie de ce bloc. Nous l'avons testé : avec Include sous un bloc Host a, les réglages du fichier inclus n'ont rien fait pour aucun autre hôte. Vous pouvez l'utiliser exprès, pour n'inclure un fichier que pour certains hôtes.

Match

Match est une forme plus puissante de Host, avec des conditions :

Match host "*.internal" user deploy
  Port 2200

Match exec "test -f /tmp/at-office"
  ProxyJump bastion

Le premier ne s'applique que si les deux conditions sont vraies. Le second exécute une commande shell et s'applique si elle se termine avec 0, ce qui permet de changer les réglages selon le réseau ou le lieu. Notez que cette commande s'exécute à chaque lecture de la configuration, même avec ssh -G.

Les conditions utiles sont host, originalhost, user, localuser, exec, tagged, final et all. host vérifie le nom après application de HostName, et originalhost vérifie ce que vous avez tapé. final fait lire la configuration une seconde fois à ssh, ce qui permet à un bloc de voir le résultat de la première passe :

Host *.corp
  HostName %h.example.com

Match final host *.example.com
  User admin

Dans OpenSSH 9.4 et les versions suivantes, vous pouvez aussi étiqueter des hôtes et les sélectionner avec Match tagged ou ssh -P :

Host web
  Tag prod

Match tagged prod
  User deploy

ProxyJump a sa propre page : utiliser ProxyJump et un serveur de rebond en SSH.

Voir le résultat avec ssh -G

ssh -G web

Cela affiche chaque réglage que ssh utiliserait pour cet hôte, avec tous les fichiers et règles appliqués, puis se termine sans se connecter. C'est le moyen le plus rapide de répondre à « pourquoi utilise-t-il cet utilisateur ? » :

ssh -G web | grep -E '^(hostname|user|port|identityfile) '

Pour savoir si votre configuration est la cause d'un problème, ignorez-la le temps d'une commande. -F none saute à la fois le fichier de l'utilisateur et celui du système :

ssh -F none user@203.0.113.10

Pour la connexion elle-même, ssh -v web affiche quelles lignes de configuration ont été appliquées.

Erreurs courantes

  • Un Host * en haut qui écrase tout ce qui suit.
  • Une option globale à la fin du fichier. Les options hors d'un bloc doivent venir avant le premier Host. À la fin, elles appartiennent au dernier bloc.
  • Une faute de frappe dans une option. ssh s'arrête avec Bad configuration option et ne se connecte à rien, sur aucun hôte. Pour une option que seules certaines versions connaissent, mettez IgnoreUnknown et le nom de l'option au-dessus.
  • Des secrets dans le fichier. Il contient des chemins vers des clés, pas des clés, et il n'a pas d'option de mot de passe. C'est ainsi qu'il doit rester.

Questions

Où se trouve le fichier de configuration SSH ?

Sous Linux et macOS, c'est ~/.ssh/config dans votre dossier personnel. Sous Windows, c'est C:\Users\nom\.ssh\config. Il n'existe pas tant que vous ne l'avez pas créé. Les réglages système de /etc/ssh/ssh_config sont lus après lui.

Pourquoi ssh ignore-t-il un réglage de ma config ?

Un autre bloc correspondant a défini la même option avant, et la première valeur l'emporte. Lancez ssh -G suivi du nom de l'hôte pour voir la valeur que ssh utilisera, et placez les hôtes précis au-dessus de Host *.

Le fichier de configuration SSH s'applique-t-il à scp, sftp et rsync ?

Oui. Ils passent par ssh pour se connecter, donc les noms d'hôtes et les options de ~/.ssh/config s'appliquent aussi, par exemple scp fichier.txt web:/tmp/.

Sources

Autres guides : Configuration et nombreux serveurs

Tous les guides