// ssh config

The ~/.ssh/config file, explained (with examples)

One small text file controls which key, user, port and host every ssh, git and scp command uses. Here's how it really works, including the two rules that trip everyone up.

Updated · 3 min read · by Pixel Worship, LLC

The SSH client reads two config files, in order: your ~/.ssh/config, then the system-wide /etc/ssh/ssh_config. Everything below applies to the macOS and Linux OpenSSH client used by ssh, git, scp, rsync and friends.

#Create it

The file doesn't exist on a fresh Mac:

Terminal
touch ~/.ssh/config
chmod 600 ~/.ssh/config

#The shape of the file

A config is a list of Host blocks. Each block starts with one or more patterns and applies its options to any host name that matches:

~/.ssh/config
Host myserver
  HostName 203.0.113.10
  User deploy
  Port 2222
  IdentityFile ~/.ssh/deploy_ed25519
  IdentitiesOnly yes

Host github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Host *
  AddKeysToAgent yes
  UseKeychain yes
  ServerAliveInterval 30

Now ssh myserver connects to 203.0.113.10 on port 2222 as deploy with the right key. Indentation is only for readability; keywords are case-insensitive.

#The options you'll actually use

OptionWhat it does
HostPatterns this block applies to (* and ? wildcards, ! to exclude)
HostNameThe real address to connect to (lets Host be a short nickname)
UserLogin user (git for Git hosts)
PortSSH port, if not 22
IdentityFilePrivate key to offer. Adds up across matching blocks
IdentitiesOnlyyes = only offer the keys named here, not everything in the agent
ProxyJumpHop through a bastion: ProxyJump bastion.example.com
ForwardAgentForward your agent to the server (only to hosts you trust)
ServerAliveIntervalSend keep-alives every N seconds to avoid dropped sessions
AddKeysToAgent / UseKeychainLoad keys into the agent and remember passphrases in the macOS Keychain
IncludePull in other config files

#Rule 1: the first value wins

For almost every option, SSH uses the first value it finds reading top to bottom, across every block that matches. Defaults in a Host * block at the top would override everything below. So:

  • put specific hosts first,
  • put Host * defaults last.

#Rule 2: IdentityFile adds up

IdentityFile is the exception. Every matching block adds its key to the list SSH will try. A key in Host * is offered to every host, after the specific one. That's why people suddenly see the wrong account on GitHub, or Too many authentication failures. Fix it with IdentitiesOnly yes and by excluding specific hosts from wildcards. The wildcards guide shows how.

#Include other files

Include keeps things tidy, but where you put it matters. An Include inside a Host block only applies to that block, so put it at the very top for global effect:

~/.ssh/config
Include ~/.ssh/config.d/*
Include ~/.ssh/easysshconfig-managed.conf

Host …

#Test before you connect

ssh -G prints exactly what SSH will use for a host, without connecting:

Terminal
ssh -G github.com | grep -E "^(hostname|user|port|identityfile|identitiesonly) "
Output
hostname github.com
user git
port 22
identitiesonly yes
identityfile ~/.ssh/id_ed25519

If there's a typo in the file, ssh -G stops with the file name and line number, so it doubles as a syntax checker.

#Common mistakes

  • Global IdentityFile lines (outside any Host block, or in Host *) that leak a key into every connection.
  • Include placed after a Host line, which silently scopes it to that host.
  • UseKeychain on Linux: it's Apple-only; add IgnoreUnknown UseKeychain above it if you share the file across machines.
  • Wrong permissions: keep the file at 600.

#Edit it visually

EasySSHConfig manages your host-to-key rules in its own file and adds a single Include line at the top of your config. It writes the exclusions so the most specific host wins, and checks every change with ssh -G, rolling back automatically if SSH rejects it. Your own blocks stay exactly as you wrote them.

Frequently asked questions

Where is the SSH config file on a Mac?

At ~/.ssh/config (that is, /Users/your-name/.ssh/config). It doesn't exist by default; create it with touch ~/.ssh/config and chmod 600 ~/.ssh/config.

Does the order of Host blocks matter?

Yes. For most options SSH uses the first value it finds, reading top to bottom, so put specific hosts first and the Host * defaults last. IdentityFile is the exception: it accumulates from every matching block.

How do I test my SSH config without connecting?

Run ssh -G hostname. It prints the fully resolved settings for that host (hostname, user, port, identity files) without opening a connection.

What's the difference between Host and HostName?

Host is the pattern SSH matches against the name you type (it can be a nickname). HostName is the real address SSH connects to.