Skip to content
Terminalia

Guide · SSH

How to set up ~/.ssh/config, with examples

Updated · 5 min read

~/.ssh/config is where OpenSSH keeps per-server settings, so instead of ssh -i ~/.ssh/id_ed25519 -p 2222 deploy@203.0.113.10 you type ssh prod. Each block starts with Host alias, followed by options like HostName, User, Port, IdentityFile or ProxyJump. scp, sftp, rsync and git read it too.

On this page

1. Create the file with the right permissions

Terminal
mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/config && chmod 600 ~/.ssh/config
open -e ~/.ssh/config

open -e opens it in TextEdit; any plain-text editor works.

2. Your first host

~/.ssh/config
Host prod
  HostName 203.0.113.10
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

Now:

Terminal
ssh prod
scp backup.sql prod:/tmp/
rsync -av ./dist/ prod:/srv/app/

What each option does:

What each option does
OptionWhat it’s for
HostThe alias you type. Accepts several names and wildcards (*, ?).
HostNameThe real address: an IP or DNS name. Defaults to the alias.
UserRemote user. Defaults to your Mac username.
PortSSH port. Defaults to 22.
IdentityFileThe private key to offer. ~ works.
ProxyJumpA bastion to hop through first (→ ProxyJump guide).

3. A real file with several servers

~/.ssh/config
# Specific hosts first
Host prod
  HostName 203.0.113.10
  User deploy
  Port 2222

Host staging
  HostName staging.example.com
  User deploy

Host bastion
  HostName bastion.example.com
  User ubuntu

Host app-1 app-2
  HostName %h.internal.example.com
  User deploy
  ProxyJump bastion

Host github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github

# Defaults last
Host *
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  AddKeysToAgent yes
  UseKeychain yes
  ServerAliveInterval 30

%h expands to the alias (app-1 → app-1.internal.example.com).

4. How matching works

OpenSSH reads the file top to bottom and, for each option, keeps the first value it finds. That’s why specific hosts go first and Host * goes last: put Host * with User root at the top and no later User line will ever apply.

To see the final settings for an alias:

Terminal
ssh -G prod | grep -E '^(hostname|user|port|identityfile|proxyjump) '

5. Passphrase-protected keys and the macOS Keychain

With AddKeysToAgent yes and UseKeychain yes (an option only Apple’s OpenSSH understands), your passphrase is stored in the Keychain and you won’t be asked again. To add it now:

Terminal
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

If you share the same config with Linux machines, add IgnoreUnknown UseKeychain at the top so Linux OpenSSH doesn’t choke on it.

6. Split the file with Include

~/.ssh/config
Include ~/.ssh/config.d/*

Put it on the first line, before any Host. Inside a Host block it only applies to that block.

Common errors

  • Bad owner or permissions on ~/.ssh/config. Other users can write to the file. Run chmod 600 ~/.ssh/config.
  • Too many authentication failures. Your agent offers every key it holds and the server gives up before reaching the right one. Add IdentitiesOnly yes and the correct IdentityFile.
  • ssh: Could not resolve hostname prod. The alias doesn’t match any Host line (check spelling and spaces), or HostName is missing.
  • An option is ignored. An earlier block (often a Host * at the top) already set it. Check with ssh -G alias.
  • Bad configuration option: usekeychain. You’re on a non-Apple OpenSSH. Add IgnoreUnknown UseKeychain at the top.
  • Host vs HostName mix-up. Host matches what you type, not the real IP. ssh 203.0.113.10 won’t pick up the Host prod block.

FAQ

Where is the SSH config file on a Mac?

Yours lives at ~/.ssh/config, that is /Users/your-name/.ssh/config. It doesn’t exist until you create it. The system-wide config is /etc/ssh/ssh_config, but leave that one alone: your personal file takes priority and survives macOS updates. In Finder, Cmd+Shift+. reveals hidden folders like .ssh.

What’s the difference between Host and HostName?

Host is the short name you type (ssh prod) and decides which block applies. HostName is the real address ssh connects to, an IP or a DNS name. Without a HostName, OpenSSH tries to connect to the alias itself, which only works if that name resolves in DNS or /etc/hosts.

Does ~/.ssh/config work with scp, rsync and git?

Yes. scp, sftp, rsync and git over SSH all use the same OpenSSH client, so they read your ~/.ssh/config. scp file prod:/tmp/ or git clone github.com:user/repo.git pick up the alias’s user, port, key and ProxyJump. So do GUI apps that run the system OpenSSH.

Related guides