Guides

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

Illustration: an open address book with little houses and keys, wires running from its pages to servers

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

  1. Create the file and lock it down.

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

    chmod 600 means only you can read and write it. SSH is strict about permissions on its files, so do it right from the start.

  2. Describe the server with a Host block. Open the file in any editor and add:

    Host prod
      HostName 203.0.113.7
      User deploy
      Port 2222
      IdentityFile ~/.ssh/work_key
    

    Host is the short name you made up. HostName is the real address. The rest is what used to be command flags. Indentation isn't required, but it reads better.

  3. 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 -G flag connects to nothing. It just prints the final settings for that name. You should see user deploy, hostname 203.0.113.7, port 2222.

  4. Connect.

    ssh prod
    

    The short name works in other SSH-based tools too: scp file.txt prod:~/, rsync, git clone prod:repo.git, remote development in your editor.

  5. 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 from IdentityFile. 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.com applies 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 your localhost:5432 while SSH is open. No need to expose it to the whole internet.

What you get

After setup you have:

  • ssh prod instead of a half-line command;
  • no forgotten ports or wrong keys;
  • the same behavior in the terminal, scp, git and your editor;
  • a one-second ssh -G name check 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.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →