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:
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:
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 30Now 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
| Option | What it does |
|---|---|
Host | Patterns this block applies to (* and ? wildcards, ! to exclude) |
HostName | The real address to connect to (lets Host be a short nickname) |
User | Login user (git for Git hosts) |
Port | SSH port, if not 22 |
IdentityFile | Private key to offer. Adds up across matching blocks |
IdentitiesOnly | yes = only offer the keys named here, not everything in the agent |
ProxyJump | Hop through a bastion: ProxyJump bastion.example.com |
ForwardAgent | Forward your agent to the server (only to hosts you trust) |
ServerAliveInterval | Send keep-alives every N seconds to avoid dropped sessions |
AddKeysToAgent / UseKeychain | Load keys into the agent and remember passphrases in the macOS Keychain |
Include | Pull 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:
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:
ssh -G github.com | grep -E "^(hostname|user|port|identityfile|identitiesonly) "hostname github.com
user git
port 22
identitiesonly yes
identityfile ~/.ssh/id_ed25519If 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
IdentityFilelines (outside any Host block, or inHost *) that leak a key into every connection. Includeplaced after a Host line, which silently scopes it to that host.UseKeychainon Linux: it's Apple-only; addIgnoreUnknown UseKeychainabove 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.