How ssh reads this file
Sources in order: command-line options, then ~/.ssh/config, then the system-wide /etc/ssh/ssh_config.
Within the file, ssh walks top to bottom through the Host blocks that match the name, and for each
option takes the first value. So:
- specific servers’ blocks go at the top;
Host *with shared settings goes last, or it overrides everything below;- one name can match several blocks:
web1matches bothHost web1andHost *.
ssh -G shows what you get for a given name: it parses the file and prints the result without connecting
anywhere.
The file is ~/.ssh/config; on Windows, C:\Users\<name>\.ssh\config. The tilde works in paths there too.
The file, block by block
Server names and addresses are placeholders: web1, web2, db1, backup1, addresses from the documentation ranges.
Include ~/.ssh/config.d/*Pull in files from a directory: the work servers’ config lives in its own file, which you can keep in another repository or not show at all. Include must come before the first Host — inside a block it only applies to that block.
default nothing included
Host web1
HostName 203.0.113.10
User example-user
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yesA short name instead of the address, user and key. IdentitiesOnly yes offers the server only this key, not every key in the agent in turn: with five keys in the agent, a server with MaxAuthTries 3 drops the connection before it gets to the right one (sshd_config).
default:User your local user namePort 22IdentitiesOnly no
Host web2 db1 backup1
HostName %h.example.org
User example-user
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yesSeveral names on one line — shared settings for a group of servers. Each has its own address, so HostName goes in separate blocks above or in config.d. %h is the name you typed in the command.
Host github-infra
HostName github.com
User git
IdentityFile ~/.ssh/github_infra
IdentitiesOnly yesA GitHub alias with its own key: a deploy key opens one repository (Server configs in git, Each key and token grants one access). In git, write the URL with the alias: git@github-infra:example-user/infra-web1.git. The user on GitHub is always git.
Host db-internal
HostName 10.0.0.5
User example-user
ProxyJump web1A server with no public address, reached through the first one. ProxyJump connects to web1 and, through it, to 10.0.0.5; the key stays on your computer and never lands on the jump host. On the command line: ssh -J web1 [email protected].
default direct
Host *
ServerAliveInterval 30
ServerAliveCountMax 3Every 30 seconds the client sends the server an empty packet; three missed replies in a row and the connection closes. The home router’s NAT doesn’t forget a quiet session, and a dead one doesn’t hang for minutes.
default:ServerAliveInterval 0 — don’t sendServerAliveCountMax 3
AddKeysToAgent yesA key with a passphrase goes into the agent on first use, and the passphrase isn’t asked again until the agent session ends (ssh-agent). Needs a running agent: on Windows, the ssh-agent service.
default no
StrictHostKeyChecking askAn unknown server gets a yes/no prompt with the fingerprint; a changed key gets a refusal. accept-new silently accepts only new servers and still complains about a changed key — good for scripts that connect to fresh machines. Ubuntu’s client config also hashes names in known_hosts (HashKnownHosts yes): the file doesn’t give away your server list, but you can’t read it by eye either.
default:StrictHostKeyChecking askHashKnownHosts no (yes on Ubuntu)
Host web1 web2 db1 backup1
ControlMaster auto
ControlPath ~/.ssh/cm/%C
ControlPersist 10mA shared connection: the first ssh web1 holds the channel, and later ssh, scp, git ride on it without logging in again — a second session opens instantly. Linux and macOS only. Create ~/.ssh/cm in advance, mode 700.
default no
ForwardAgent yesDon’t turn on agent forwarding, neither for Host * nor for your servers: root on the server can sign anything with your agent while the session is open. For jumping through a server there’s ProxyJump (ssh-agent).
default no
Tokens in values
| Token | What it expands to |
|---|---|
%h |
the host name after HostName substitution; in the HostName line itself, the name from the command |
%n |
the name exactly as typed in the command |
%r |
the remote user |
%p |
the port |
%C |
a hash of %l%h%p%r — a short name for the ControlPath socket |
%d |
your local home directory |
If it doesn’t work
A setting in a host block has no effect
- Cause
- Higher up in the file there’s
Host *or another matching block with the same setting — and the first value wins. - Fix
ssh -G web1 | grep -i <setting>shows the result. Specific host blocks go up,Host *goes at the end of the file.
Bad owner or permissions on /home/me/.ssh/config
- Cause
- The group or others can write to the file.
- Fix
chmod 600 ~/.ssh/config.
On Windows the connection fails with ControlMaster
- Cause
- OpenSSH for Windows can’t share a connection over a Unix socket: with any
ControlPathssh fails —getsockname failed: Not a socket, thenRead from remote host …: Unknown error. - Fix
- Keep the
ControlMasterblock only in the Linux and macOS config, or under aMatch execthat doesn’t fire on Windows.
git clone git@github-infra:… — Could not resolve hostname github-infra
- Cause
- Git runs an
sshthat reads a different config: for example, Git for Windows with its ownssh.exeand a differentHOME. - Fix
- Tell git which
sshto use:git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe, and checkssh -G github-infra.
Through ProxyJump — channel 0: open failed: administratively prohibited
- Cause
- The jump host has
AllowTcpForwarding no, and a jump works through forwarding. - Fix
- Allow forwarding there:
AllowTcpForwarding yes, or at least aMatch User example-userblock with that line.
How to check
ssh -G parses the file for a name and prints the result without connecting. For web1 from the file above:
ssh -G web1 | grep -E '^(hostname|user|port|identityfile|identitiesonly|serveraliveinterval) '
# user example-user
# hostname 203.0.113.10
# port 22
# identitiesonly yes
# serveraliveinterval 30
# identityfile ~/.ssh/id_ed25519
The jump — which path ssh will take:
ssh -G db-internal | grep -i '^proxyjump'
# proxyjump web1
The git alias:
ssh -T github-infra
# Hi example-user/infra-web1! You've successfully authenticated, but GitHub does not provide shell access.