SSH Config File Setup to Stop Typing Long Server Commands
If you connect to more than two servers, you probably type the same long command a dozen times a day: a username, an IP address, a non-standard port and a path to a key file.

If you connect to more than two servers, you probably type the same long command a dozen times a day: a username, an IP address, a non-standard port and a path to a key file. One typo and you get "Permission denied" or, worse, you land on the wrong box. An SSH config file fixes this by turning every one of those commands into a short alias like "ssh db" that you can trust.
The file lives at ~/.ssh/config on Linux and macOS, and at C:\Users\yourname\.ssh\config on Windows with the built-in OpenSSH client. It is plain text, it needs no extra software, and it takes about ten minutes to set up for a typical small team's servers. Below is the setup I use on every new laptop, plus the parts most guides skip.
What an SSH config file actually does
Every time you run ssh, the client reads two files before it connects: your personal config and the system-wide one in /etc/ssh/ssh_config. It looks for a Host block whose name matches what you typed, then applies the settings inside it. The first value it finds for each option wins, which matters later.
So instead of typing "ssh -p 2222 -i ~/.ssh/id_ed25519_work [email protected]", you write a block once and then type "ssh web". The same alias works for scp, rsync, git over SSH and most editors with remote features, because they all call the same client underneath.
Setting up your first SSH config file in five steps
- Create the file with the right permissions. Run "touch ~/.ssh/config" and then "chmod 600 ~/.ssh/config". OpenSSH refuses to use a config that other users can write to, and the error message is not always obvious.
- Add one Host block per server. Each block starts with a line like "Host web" and is followed by indented options. The indentation is only for you; the client ignores it.
- Fill in the four options you always need. HostName is the real address, User is the login name, Port is only needed if it is not 22, and IdentityFile points to the private key.
- Add "IdentitiesOnly yes" to each block. Without it, your SSH agent may offer every key it holds, and many servers drop the connection after five failed attempts. If you have six keys loaded, you can be locked out before the right one is tried.
- Test with verbose output. Run "ssh -v web" once. The first lines show which config lines were applied, so you can see immediately if a block did not match.
A complete block for a small web server looks like this, one option per line:
- Host web
- HostName 203.0.113.40
- User deploy
- Port 2222
- IdentityFile ~/.ssh/id_ed25519_work
- IdentitiesOnly yes
If your team is moving private keys onto physical tokens, the same blocks still work; our guide to hardware security keys for a small team covers generating a key that lives on the device.
Options worth adding once the basics work
Keeping idle sessions alive
Home routers and cloud load balancers often drop idle TCP connections after 5 to 15 minutes. Adding "ServerAliveInterval 60" and "ServerAliveCountMax 3" under a "Host *" block makes the client send a small keepalive every minute and give up after three missed replies. Your terminal stops freezing when you come back from lunch.
Jumping through a bastion host
If your database server is only reachable from inside a private network, "ProxyJump bastion" in the database block tells SSH to hop through the bastion first. You type "ssh db" and the client handles both connections. This replaces the old ProxyCommand trick with netcat and is supported in OpenSSH 7.3 and later, which covers every maintained distribution.
Reusing one connection
ControlMaster, ControlPath and ControlPersist let several terminal tabs share one TCP connection. The second "ssh web" opens almost instantly, and tools like Ansible that open dozens of sessions get noticeably faster. A sensible setting is "ControlPersist 10m" with ControlPath set to a file under ~/.ssh/sockets.
Order matters more than people expect
Because the first match wins, a "Host *" block at the top will override everything below it. Put specific hosts first and the catch-all defaults at the very bottom. Wildcards also work in the middle: "Host *.staging.internal" can set a shared user and key for every staging machine, while a more specific block above it handles the one odd server.
The Include directive is the other tool worth knowing. A line like "Include ~/.ssh/config.d/*" at the top of the file pulls in separate files, so you can keep work hosts, personal hosts and client projects apart. It must appear before any Host block, or it will only apply inside the block that precedes it.
Why I do not commit my SSH config file to a shared repo
A common tip is to put a team-wide SSH config in a Git repository so everyone gets the same aliases. It sounds tidy, and for a two-person team it can work. In practice I have seen it go wrong in three ways.
First, IdentityFile paths differ between people, so the shared file either has broken paths or forces everyone to name their keys the same way. Second, it exposes your internal hostnames, bastion addresses and port choices to anyone who can read the repo, including contractors who left months ago. Third, when someone adds "ForwardAgent yes" to a shared block for convenience, every teammate starts forwarding their agent to servers they may not fully trust, and a root user on that server can use the forwarded agent to log in elsewhere as them.
A better split is to share a short document listing hostnames and which bastion to use, then let each person write their own config. If you want consistency, share a template file through Include and keep keys and agent settings personal. The same thinking applies to environment variables, which is why per-directory tools such as direnv for per project environment variables keep secrets out of the repository.
A few security habits that cost nothing
- Leave ForwardAgent off by default and turn it on only for hosts you control. ProxyJump usually removes the need for it.
- Set "HashKnownHosts yes" if you work on shared machines, so the known_hosts file does not list every server you connect to in plain text.
- Never set "StrictHostKeyChecking no" globally. It disables the check that warns you when a server's identity changes, which is exactly the warning you want during a man-in-the-middle attempt.
- Pair your config with a host firewall on the server side. Our UFW firewall setup guide shows how to allow your custom SSH port before enabling the rules.
Once these are in place, review the file every few months. Servers get retired, and stale aliases pointing at recycled IP addresses are a quiet way to send your key to someone else's machine.
Frequently asked questions
Where is the SSH config file on Windows?
With the OpenSSH client that ships with Windows 10 and 11, it is at C:\Users\yourname\.ssh\config. Create the .ssh folder if it does not exist and save the file with no extension. PuTTY does not read this file; it stores sessions in the registry instead.
Why is my SSH config file being ignored?
The most common causes are wrong permissions, a file saved with a .txt extension, or a "Host *" block placed above the specific host. Run "ssh -v alias" and read the lines that start with "debug1: Reading configuration data" to see which file and which blocks were applied.
Can I use the same SSH config for Git hosting?
Yes. A block such as "Host github-work" with HostName set to the provider's SSH hostname and its own IdentityFile lets you keep a work key and a personal key apart. You then use the alias in the remote URL, and Git picks the right key without any extra flags.
More in Dev Tools
Dev Tools
Git includeIf Setup for Work and Personal Identities
The commit that made me fix this properly had my personal address on it, sitting in a client repository, pushed to a branch...
Dev Tools
Sign Git Commits With an SSH Key in Fifteen Minutes
Anyone can set their Git name and email to yours. It takes one line of config, no password and no access to your accounts, and...
Dev Tools
Git Bisect to Find the Commit That Broke Your Build
The build passed on Monday and fails on Thursday, and there are 140 commits in between.