~/.ssh/config reference~/.ssh/config lets you give each server a short name and store how to reach it, so ssh web replaces ssh -p 2222 -i ~/.ssh/id_ed25519_work [email protected]. It's a plain text file of Host blocks, each followed by indented settings. Create it if it doesn't exist.
Every example on this page was checked with ssh -G against OpenSSH 10.
Host bastion
HostName bastion.example.com
User ops
Host web
HostName 10.0.0.12
User deploy
Port 2222
IdentityFile ~/.ssh/id_ed25519_work
IdentitiesOnly yes
ProxyJump bastion
Host *.internal
User admin
Host *
ServerAliveInterval 30
ServerAliveCountMax 3
AddKeysToAgent yes
With that file:
ssh web connects to 10.0.0.12 on port 2222 as deploy, with the work key, through the bastion.ssh db.internal connects to db.internal as admin.Host *.The same names work for everything built on SSH: scp file web:/tmp/, rsync -a dir/ web:dir/, git clone web:repo.git and ssh-copy-id web.
| Option | What it sets |
|---|---|
Host | Starts a block. One or more names or patterns; the settings below it apply when the name you type matches |
HostName | The real address or DNS name to connect to. Without it, SSH uses the name you typed |
User | The login name, the part before @ |
Port | The server's SSH port (default 22) |
IdentityFile | Path to the private key to use |
IdentitiesOnly | yes offers only the keys named in IdentityFile, not every key in the agent |
ProxyJump | Connect through another host first (same as ssh -J) |
ServerAliveInterval | Seconds of silence before the client checks the server is still there |
ForwardAgent | yes lets the server use your local SSH agent (same as ssh -A) |
LocalForward | A port forward set up on every connection (same as ssh -L; see SSH port forwarding) |
AddKeysToAgent | yes adds a key to the running agent the first time it's used |
Option names aren't case sensitive, and an option can be written Port 2222 or Port=2222. Lines starting with # are comments. The indentation is only for reading; a block runs until the next Host or Match line. The full list is in man ssh_config.
Host github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
IdentitiesOnly yes
Without IdentityFile, SSH tries its default key files (~/.ssh/id_ed25519, ~/.ssh/id_ecdsa, ~/.ssh/id_rsa and a few others) plus anything in your agent. That's fine with one key. With many, a server can reject the connection with "Too many authentication failures" before SSH reaches the right one, and that's what IdentitiesOnly yes prevents.
A second GitHub account on the same machine works with an alias:
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work
IdentitiesOnly yes
Then clone with git clone github-work:company/repo.git. The one-off command-line equivalent of IdentityFile is ssh -i ~/.ssh/key user@host.
ProxyJump bastion makes SSH connect to the bastion first and open the real connection through it. Authentication to the final server still happens from your machine, so no key needs to sit on the bastion. Several hops are comma-separated: ProxyJump bastion1,bastion2. On the command line it's ssh -J bastion web.
Host *
ServerAliveInterval 30
ServerAliveCountMax 3
Routers and firewalls often drop connections that look idle. With these settings the client sends a small message through the encrypted connection after 30 seconds of silence, and gives up after three unanswered messages, about 90 seconds. That both keeps quiet sessions open and makes a really dead connection fail in a minute and a half instead of hanging.
For each setting, SSH uses the first value it finds and ignores later ones. It reads in this order:
-p, -l, -i, -o).~/.ssh/config, top to bottom./etc/ssh/ssh_config.So specific blocks go at the top and Host * goes at the bottom. A User in Host * at the top of the file would beat every other block's User.
Patterns in Host lines: * matches any run of characters, ? matches one, and ! excludes. Host *.internal !build.internal matches every host ending in .internal except build.internal. A host can match several blocks; it collects the first value of each setting across all of them.
When a setting isn't doing what you expect, ask SSH what it resolved, without connecting:
ssh -G web | grep -E '^(hostname|user|port|identityfile|proxyjump) '
Include ~/.ssh/config.d/*
Put Include at the top of the file. An Include placed after a Host line belongs to that block and only applies when that block matches, which is rarely what's intended. Relative paths are taken from ~/.ssh, and wildcards are allowed, so one file per client or project works well.
SSH refuses to use a config file that other users can write to, with "Bad owner or permissions on ~/.ssh/config". Fix it with:
chmod 600 ~/.ssh/config
chmod 700 ~/.ssh
Private keys need the same treatment (chmod 600); SSH ignores a private key that other users can read.
An iPhone has no ~/.ssh/config to edit, and Shell Drop doesn't import one. Each saved connection holds what a basic Host block would: the label you tap, the host, the port, the user name, and a key or password. Keys are made on the device or imported from your existing OpenSSH keys; SSH keys on iPhone covers that, and ssh-copy-id covers putting the public half on the server.
Shell Drop has no ProxyJump setting. For a server behind a bastion, connect to the bastion and run ssh onward from there; with agent forwarding on for that connection, the second hop can use the key on your phone. On the bastion itself, a ~/.ssh/config with the inner hosts makes that second hop a short command. SSH on iPhone walks through the rest of the setup.
Your own settings go in ~/.ssh/config, which you create if it isn't there. The system-wide defaults are in /etc/ssh/ssh_config. The server's settings are a different file, /etc/ssh/sshd_config.
Add IdentityFile ~/.ssh/your_key under the Host block. Add IdentitiesOnly yes too if you have several keys in an agent, so SSH offers only that key.
The first value SSH finds for each setting. Options on the command line come first, then ~/.ssh/config from top to bottom, then /etc/ssh/ssh_config. Put specific Host blocks at the top and Host * at the bottom.
Run ssh -G hostname. It prints every setting SSH would use for that host after reading all the config files, without connecting.
No. On iPhone and iPad each saved connection holds the host, port, user name and a key or password, the same things a basic Host block sets. There is no ProxyJump setting; connect to the bastion and SSH onward from there.