Qvantor logo QvantorInfrastructure, explained plainly
Dev Tools

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.

A laptop on a wooden desk showing a terminal window with an open text file of server aliases beside a small black server box

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

IV
Ilkka Varis

Ilkka has run mail servers for small companies since the days of hand edited DNS zones.

More posts by Ilkka

More in Dev Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto