How to set up ~/.ssh/config — short server names instead of long commands

For the third time today you type ssh -i ~/.ssh/work_key -p 2222 [email protected]. And for the third time you get the port wrong.
You could just type ssh prod. SSH will take everything else from one text file. Let's set it up in five minutes.
And along the way we'll cover the trap that makes many configs "not work" even though they're written correctly.
What this file is
~/.ssh/config is SSH's address book. For each server you write once: address, username, port, key. Then you reach the server by a short name.
It's an ordinary text dotfile in the .ssh folder of your home directory. If SSH is new to you, start with what SSH is.
Step by step: your first server
-
Create the file and lock it down.
mkdir -p ~/.ssh touch ~/.ssh/config chmod 600 ~/.ssh/configchmod 600means only you can read and write it. SSH is strict about permissions on its files, so do it right from the start. -
Describe the server with a
Hostblock. Open the file in any editor and add:Host prod HostName 203.0.113.7 User deploy Port 2222 IdentityFile ~/.ssh/work_keyHostis the short name you made up.HostNameis the real address. The rest is what used to be command flags. Indentation isn't required, but it reads better. -
Check that SSH understood you. Don't connect yet — first ask SSH what it's about to do:
ssh -G prod | grep -E '^(user|hostname|port) 'The
-Gflag connects to nothing. It just prints the final settings for that name. You should seeuser deploy,hostname 203.0.113.7,port 2222. -
Connect.
ssh prodThe short name works in other SSH-based tools too:
scp file.txt prod:~/,rsync,git clone prod:repo.git, remote development in your editor. -
Add shared settings for all servers. For example, a keep-alive so the connection doesn't drop by itself:
Host * ServerAliveInterval 30*means "any server." And this is where the trap begins.
The main trap: the first match wins
Intuition says: shared settings at the top, specific ones below, and the specific ones will "override" them. That's how CSS works.
SSH does the opposite. For each option, SSH takes the first value it finds and never changes it after that.
I checked it on a real config:
Host *
User root
Port 2200
Host prod
HostName 203.0.113.7
User deploy
Port 22
ssh -G prod prints user root and port 2200. The Host * block sits higher and "claimed" those options first. The User deploy and Port 22 lines are simply ignored. With no warning at all.
Rule: specific servers at the top, Host * at the very end of the file. Then the shared block fills in only what you didn't set explicitly for a server.
A second small trap: names in Host are case-sensitive. A Host prod block won't apply to ssh PROD — SSH will treat PROD as the server's address.
What else is worth putting in the config
IdentitiesOnly yes— try only the key fromIdentityFile. It saves you when you have many keys and the server says "Too many authentication failures": SSH tried them all and hit the attempt limit.- Several names per block.
Host prod production— both names lead to the same server. - Patterns.
Host *.staging.example.comapplies the settings to every server with that ending. ProxyJump bastion— connect to a server through an intermediate one. One line instead of logging into the bastion separately.LocalForward 5432 localhost:5432— forward a port. The database on the server becomes available on yourlocalhost:5432while SSH is open. No need to expose it to the whole internet.
What you get
After setup you have:
ssh prodinstead of a half-line command;- no forgotten ports or wrong keys;
- the same behavior in the terminal,
scp,gitand your editor; - a one-second
ssh -G namecheck when something goes wrong.
FAQ
How do I do the same on Windows?
Windows 10 and 11 ship with OpenSSH, and the file lives at C:\Users\name\.ssh\config. The format is the same; ssh -G and ssh prod work in PowerShell.
Can I split the config into several files?
Yes, with the Include directive, for example Include ~/.ssh/config.d/*. Put it at the top of the file: otherwise the included blocks end up inside the last Host above it.
Do I need to restart anything after editing?
No. SSH rereads the file on every connection — save it and use it right away.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





