SSH Config Datei (~/.ssh/config) mit Beispielen

Wenn Sie eine Verbindung zu mehreren Servern herstellen, werden Sie Befehle wie ssh -p 2222 -i ~/.ssh/id_ed25519_web janos@203.0.113.10 schnell leid sein. In der Konfigurationsdatei des SSH-Clients, der Datei ~/.ssh/config, können Sie jedem Server einen Kurznamen zusammen mit der Adresse, dem Benutzernamen, dem Port und dem Schlüssel zuweisen; von da an reicht es aus, einfach ssh web1 einzugeben. Derselbe Name funktioniert auch bei den Befehlen scp, rsync, sftp und git.

Die Beispiele in diesem Artikel wurden im November 2026 getestet: Als Client wurden eine virtuelle Maschine mit AlmaLinux 10.2 (OpenSSH 9.9) und macOS (OpenSSH 10.3) verwendet, als Server dienten Maschinen mit Debian 13 (OpenSSH 10.0) und AlmaLinux 10.2. Die Einstellungen müssen auf Ihrem eigenen Rechner (Laptop, Desktop-PC) vorgenommen werden, nicht auf dem Server; sie lassen sich auf dieselbe Weise auch für einen Linux-VPS anwenden.

Wo befindet sich die Datei?

System	Eigene Einstellungen	Für alle Benutzer
Linux, macOS	`~/.ssh/config`	`/etc/ssh/ssh_config`
Windows 10 und 11 (integriertes OpenSSH)	`C:\Users\<Name>\.ssh\config`	`C:\ProgramData\ssh\ssh_config`

Die Datei ist standardmäßig nicht vorhanden; Sie müssen sie selbst erstellen. Die Windows-Pfade entsprechen der Microsoft-Dokumentation; speichern Sie die Datei dort ohne Dateiendung (config, nicht config.txt).

Verwechseln Sie dies bitte nicht mit der Konfigurationsdatei des Servers: Die Datei /etc/ssh/sshd_config (mit dem Buchstaben d) auf dem Server regelt, wer sich wie anmelden darf. Diesem Thema widmet sich der Artikel Sicherheitseinstellungen des SSH-Servers; die Grundlagen von SSH werden im Artikel Linux Secure Shell (SSH) erläutert.

Der erste Eintrag

Erstellen Sie das Verzeichnis und die Datei mit den entsprechenden Berechtigungen:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/config
chmod 600 ~/.ssh/config
nano ~/.ssh/config

Eintrag für einen Server:

Host web1
    HostName 203.0.113.10
    Port 2222
    User janos
    IdentityFile ~/.ssh/id_ed25519_web
    IdentitiesOnly yes

Nach dem Speichern lautet die Verbindung:

ssh web1

Dies funktioniert genau wie der Befehl ssh -p 2222 -i ~/.ssh/id_ed25519_web janos@203.0.113.10. Die Einrückung der Zeilen nach der Zeile Host ist nicht zwingend erforderlich, sondern dient lediglich der besseren Lesbarkeit der Datei; der Eintrag reicht bis zur nächsten Host-Zeile.

Die gängigsten Einstellungen

Einrichtung	Wozu dient das?	Entsprechung in der Befehlszeile
`Host`	Der Kurzname (oder das Muster), auf den sich der Eintrag bezieht
`HostName`	Die tatsächliche Adresse oder IP-Adresse des Servers
`User`	Benutzername	`-l janos` oder `janos@`
`Port`	Der SSH-Port, falls dieser nicht 22 ist	`-p 2222`
`IdentityFile`	Die Datei mit dem privaten Schlüssel	`-i ~/.ssh/kulcs`
`IdentitiesOnly yes`	Nur den angegebenen Schlüssel versuchen
`ServerAliveInterval`	Lebenszeichen im angegebenen Sekundenabstand senden	`-o ServerAliveInterval=60`
`ProxyJump`	Verbindung über einen Zwischenserver	`-J bastion`
`LocalForward`	Lokale Portweiterleitung	`-L 8080:127.0.0.1:80`
`DynamicForward`	SOCKS-Proxy	`-D 1080`
`ControlMaster`, `ControlPath`, `ControlPersist`	Eine Verbindung für mehrere Sitzungen gemeinsam nutzen

Bei den Bezeichnungen der Einstellungen spielt die Groß- und Kleinschreibung keine Rolle (hostname und HostName sind identisch). Die vollständige Liste kann mit dem Befehl man ssh_config eingesehen werden.

Schlüssel: IdentityFile und IdentitiesOnly

Wenn Sie über mehrere Schlüssel verfügen, gibt die Option IdentityFile an, welchen Schlüssel der Client für den jeweiligen Server verwendet. Ohne die Option IdentitiesOnly yes probiert der Client zunächst auch die im SSH-Agenten (ssh-agent) gespeicherten Schlüssel sowie die Schlüssel mit den Standardnamen (~/.ssh/id_ed25519, ~/.ssh/id_rsa usw.) aus. Bei einer großen Anzahl von Schlüsseln kann der Server die Verbindung bereits vor dem Finden des richtigen Schlüssels mit der Fehlermeldung Too many authentication failures abbrechen, da die Anzahl der fehlgeschlagenen Versuche begrenzt ist.

Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes

Ein Schlüsselpaar können Sie mit dem Befehl ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_web erstellen, den öffentlichen Schlüssel können Sie mit dem Befehl ssh-copy-id -i ~/.ssh/id_ed25519_web.pub web1 kopieren. Die Schritte zur Einrichtung des Schlüsselzugangs finden Sie im Artikel Wie stelle ich über SSH eine Verbindung zu meinem VPS her?.

Muster und Reihenfolge: Der erste Treffer gilt

Hinter dem Host können Sie mehrere Namen und Muster angeben: * steht für eine beliebige Zeichenfolge, ? für ein einzelnes Zeichen und ! schließt etwas aus.

Host web1
    HostName 203.0.113.10

Host web2
    HostName 203.0.113.11

# Für alle Hosts, deren Name mit web beginnt
Host web*
    User deploy
    Port 2222

# Für alle Hosts außer dem alten Server
Host * !regi-szerver
    ServerAliveInterval 60

Der Client liest die Datei von oben nach unten und verwendet bei jeder Einstellung den ersten gefundenen Wert; nachfolgende, ebenfalls passende Blöcke überschreiben diese Einstellung nicht mehr, sondern füllen lediglich die noch nicht angegebenen Werte aus. Im obigen Beispiel erhält web1 die Adresse aus seinem eigenen Block, den Benutzer und den Port aus dem web*-Block sowie den Lebenszeichen-Wert aus dem Host *-Block.

Daraus ergibt sich die wichtigste Regel: Der allgemeine Host *-Block muss am Ende der Datei stehen. Im Test wurde ein Host *-Block, der die Zeile User root enthielt, an den Anfang der Datei gesetzt, woraufhin auch web1 den root-Benutzer erhielt, obwohl in seinem eigenen Block User admin angegeben war.

Die in der Befehlszeile angegebenen Schalter haben Vorrang vor allen anderen Einstellungen: Der Befehl ssh -l janos web1 stellt unabhängig von der Datei eine Verbindung mit dem Benutzer janos her.

Keepalive: Die inaktive Verbindung darf nicht unterbrochen werden

Wenn die Verbindung nach einigen Minuten Inaktivität mit dem Fehler Broken pipe oder Connection reset unterbrochen wird, ist in der Regel ein Router oder eine Firewall dafür verantwortlich, dass Verbindungen ohne Datenverkehr getrennt werden. Das ServerAliveInterval-Intervall sendet alle angegebenen Sekunden ein Lebenszeichen über den verschlüsselten Kanal, sodass die Verbindung nicht als inaktiv erscheint:

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

ServerAliveCountMax 3 bedeutet, dass der Client die Verbindung nach drei unbeantworteten Lebenszeichen (hier ca. drei Minuten) trennt, sodass das Terminal auch bei einem tatsächlich nicht erreichbaren Server nicht unbegrenzt hängen bleibt.

ProxyJump: Verbindung über einen Zwischenserver

Wenn ein Server nicht direkt über das Internet, sondern nur über einen Zwischenserver (Bastion, Jump-Host) erreichbar ist, leitet ProxyJump Sie in einem Schritt dorthin weiter:

Host bastion
    HostName bastion.pelda.hu
    User janos
    IdentityFile ~/.ssh/id_ed25519_web

Host belso
    HostName 10.0.0.5
    User janos
    IdentityFile ~/.ssh/id_ed25519_web
    ProxyJump bastion

Der Befehl ssh belso verbindet sich zunächst mit dem bastion-Rechner und eröffnet über diesen einen verschlüsselten Kanal zum Port 22 des internen Rechners. Sie melden sich auf beiden Rechnern von Ihrem eigenen Rechner aus mit Ihrem eigenen Schlüssel an: Der private Schlüssel gelangt nicht auf den Zwischenrechner, und es ist auch keine Agent-Weiterleitung (ForwardAgent) erforderlich.

Im Test griff der macOS-Client über einen AlmaLinux-10.2-Rechner auf einen Debian-13-Rechner zu, dessen Adresse vom Client aus nicht direkt erreichbar war (der Befehl ssh -o ProxyJump=none belso führte aufgrund einer Zeitüberschreitung zu einem Fehler). Die Ausgabe von ssh -v belso zeigt auch den Zwischenschritt an (die Adressen wurden an das obige Beispiel angepasst):

debug1: Setting implicit ProxyCommand from ProxyJump: ssh -v -W '[%h]:%p' bastion
Authenticated to bastion.pelda.hu ([203.0.113.20]:22) using "publickey".
Authenticated to 10.0.0.5 (via proxy) using "publickey".

Sie können mehrere Zwischenserver durch Kommas getrennt angeben (ProxyJump bastion1,bastion2); für den gelegentlichen Gebrauch reicht auch der Schalter -J: ssh -J bastion janos@10.0.0.5.

Portweiterleitung: LocalForward und DynamicForward

Auf einen Dienst, der ausschließlich lokal auf dem Server (127.0.0.1) läuft – beispielsweise eine Datenbank oder ein Web-Admin-Panel –, können Sie auch von Ihrem eigenen Rechner aus über einen SSH-Tunnel zugreifen:

Host web1-alagut
    HostName 203.0.113.10
    User janos
    IdentityFile ~/.ssh/id_ed25519_web
    # Port 8080 des eigenen Rechners -> 127.0.0.1:8000 auf dem Server
    LocalForward 8080 127.0.0.1:8000
    # SOCKS-Proxy auf Port 1080 des eigenen Rechners
    DynamicForward 1080

# Tunnel im Hintergrund aufbauen, ohne Shell
ssh -f -N web1-alagut

# Port 8000 des Servers ist jetzt auf dem eigenen Rechner erreichbar
curl http://127.0.0.1:8080/

Im Test hat der Client die Ports 8080 und 1080 nur für die Adressen 127.0.0.1 und ::1 geöffnet, sodass die übrigen Rechner im Netzwerk keinen Zugriff darauf hatten. Sowohl der Befehl curl http://127.0.0.1:8080/ als auch curl --socks5-hostname 127.0.0.1:1080 http://localhost:8000/ lieferten die Seite des Webservers zurück, der nur lokal auf dem Server läuft. Die Nutzung des SOCKS-Proxys im Browser wird im Artikel Einrichten eines SSH-SOCKS-Proxys auf einem Linux-Server beschrieben.

Sie können den im Hintergrund laufenden Tunnel durch Beenden des Prozesses schließen oder, falls Sie die unten beschriebene geteilte Verbindung nutzen, mit dem Befehl ssh -O exit web1-alagut.

Gemeinsame Verbindung: ControlMaster

Wenn Sie sich häufig mit demselben Server verbinden (zahlreiche scp-, rsync- oder git-Vorgänge, mehrere Terminalfenster), können Sie die erste Verbindung offen halten, sodass die weiteren Vorgänge über diese Verbindung laufen, ohne dass Sie sich erneut anmelden müssen:

mkdir -p ~/.ssh/cm
chmod 700 ~/.ssh/cm

Host *
    ControlMaster auto
    ControlPath ~/.ssh/cm/%r@%h:%p
    ControlPersist 10m

ControlPath ist die Socket-Datei der gemeinsam genutzten Verbindung (%r steht für den Benutzer, %h für die Adresse und %p für den Port), während ControlPersist 10m bedeutet, dass die Verbindung nach dem Schließen der letzten Sitzung noch zehn Minuten lang offen bleibt. Im Test dauerte der erste ssh web1 true-Befehl 0,13 Sekunden, der zweite über die gemeinsam genutzte Verbindung 0,006 Sekunden; bei einem Remote-Server, einem passwortgeschützten Schlüssel oder zweistufiger Authentifizierung ist der Unterschied deutlich größer.

# Fut-e megosztott kapcsolat?
ssh -O check web1

# Gemeinsame Verbindung schließen
ssh -O exit web1

Sitzungen, die über die geteilte Verbindung gestartet wurden, werden zusammen mit der Hauptverbindung unterbrochen. Der in Windows integrierte OpenSSH-Client unterstützt diese Funktion laut der Beschreibung des Win32-OpenSSH-Projekts nicht (wir haben dies nicht getestet); lassen Sie diese Zeilen dort weg.

Include: Einstellungen in mehreren Dateien

Bei einer großen Anzahl von Servern können Sie die Einträge auch in separaten Dateien organisieren:

Include config.d/*.conf

Host *
    ServerAliveInterval 60

Der relative Pfad bezieht sich auf das Verzeichnis ~/.ssh, sodass die obige Zeile die Dateien mit der Endung .conf im Verzeichnis ~/.ssh/config.d/ einliest. Fügen Sie die Zeile Include an den Anfang der Datei vor jedem Host-Block ein: Ein Include innerhalb eines Host-Blocks ist nur dann gültig, wenn der Block passt. Im Test blieb der Eintrag Host b einer per Include nach einem Host a-Block eingebundenen Datei wirkungslos; an den Anfang der Datei gesetzt, funktionierte er.

Wie lautet die tatsächliche Konfiguration? ssh -G

Sollten Sie sich nicht sicher sein, welcher Wert aus welchem Block gilt, gibt der Befehl ssh -G alle tatsächlich für den jeweiligen Namen verwendeten Einstellungen aus, ohne eine Verbindung herzustellen:

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

Dies ist die beste Methode, um Fehler zu finden, die auf die Reihenfolge oder ein falsch geschriebenes Muster zurückzuführen sind. Die einzelnen Schritte der tatsächlichen Verbindung werden durch den Befehl ssh -v web1 angezeigt.

Berechtigungen: „Bad owner or permissions“

Der SSH-Client weigert sich, eine Konfigurationsdatei zu verwenden, die auch von anderen Benutzern geändert werden kann. In diesem Fall bricht er mit folgender Fehlermeldung ab:

Bad owner or permissions on /home/janos/.ssh/config

Im Test lösten dies die Berechtigung 666 und – da die primäre Gruppe des Benutzers noch weitere Mitglieder hatte – auch die Berechtigung 664 aus. Die Korrektur:

chmod 600 ~/.ssh/config
chmod 700 ~/.ssh

Stellen Sie sicher, dass Sie der Eigentümer der Datei sind (chown $USER ~/.ssh/config), falls Sie diese beispielsweise mit sudo bearbeitet haben und sie dadurch in den Besitz von root übergegangen ist. Weitere Informationen zu den Berechtigungen finden Sie unter: Dateiberechtigungen (chmod, chown) unter Linux.

Der Kurzname in anderen Programmen

Die Konfigurationsdatei wird von allen auf OpenSSH basierenden Programmen gelesen, sodass der Kurzname überall dort funktioniert, wo eine Serveradresse angegeben werden muss:

# Dateien kopieren
scp mentes.tar.gz web1:/home/janos/
rsync -av ./public/ web1:/var/www/html/
sftp web1

# Git-Repository auf dem Server
git clone web1:repo.git

Im Test funktionierten alle Verfahren; rsync erst, nachdem wir das rsync-Paket auch auf dem Debian-Server installiert hatten (es ist im Debian-13-Cloud-Image standardmäßig nicht enthalten, und rsync ist auf beiden Seiten erforderlich). Die Einzelheiten zur Dateikopie werden im Artikel Dateien zwischen Servern kopieren (scp, rsync, sftp) erläutert.

Laut ihrer Dokumentation liest auch das Plugin „Remote - SSH“ von Visual Studio Code die Rechner aus dieser Datei aus (in der Liste Remote-SSH: Connect to Host... werden die Host-Namen angezeigt), ebenso wie viele grafische SFTP-Clients und Terminalprogramme.

Vollständiges Beispiel

Include config.d/*.conf

Host web1
    HostName 203.0.113.10
    User janos
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_web
    IdentitiesOnly yes

Host bastion
    HostName bastion.pelda.hu
    User janos
    IdentityFile ~/.ssh/id_ed25519_web

Host belso
    HostName 10.0.0.5
    User janos
    IdentityFile ~/.ssh/id_ed25519_web
    ProxyJump bastion

Host db-alagut
    HostName 203.0.113.10
    User janos
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_web
    LocalForward 3307 127.0.0.1:3306

# Allgemeine Einstellungen immer ans Ende
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    ControlMaster auto
    ControlPath ~/.ssh/cm/%r@%h:%p
    ControlPersist 10m