The SSH config file: a practical ~/.ssh/config reference

11 November 2026 · Daniel Bilsborough · Reviewed 11 November 2026

~/.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.

A sample ssh config

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:

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.

The options you'll use most

OptionWhat it sets
HostStarts a block. One or more names or patterns; the settings below it apply when the name you type matches
HostNameThe real address or DNS name to connect to. Without it, SSH uses the name you typed
UserThe login name, the part before @
PortThe server's SSH port (default 22)
IdentityFilePath to the private key to use
IdentitiesOnlyyes offers only the keys named in IdentityFile, not every key in the agent
ProxyJumpConnect through another host first (same as ssh -J)
ServerAliveIntervalSeconds of silence before the client checks the server is still there
ForwardAgentyes lets the server use your local SSH agent (same as ssh -A)
LocalForwardA port forward set up on every connection (same as ssh -L; see SSH port forwarding)
AddKeysToAgentyes 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.

IdentityFile: choosing the key

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: going through a bastion

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.

ServerAliveInterval: stopping idle disconnects

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.

Which setting wins: precedence and wildcards

For each setting, SSH uses the first value it finds and ignores later ones. It reads in this order:

  1. Options on the command line (-p, -l, -i, -o).
  2. ~/.ssh/config, top to bottom.
  3. /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: splitting the file up

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.

Permissions

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.

The same settings on an iPhone or iPad

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.

Questions

Where is the SSH config file?

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.

How do I set an identity file in the SSH 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.

Which setting wins if a host matches more than one block?

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.

How do I check what SSH will actually use for a host?

Run ssh -G hostname. It prints every setting SSH would use for that host after reading all the config files, without connecting.

Does Shell Drop read ~/.ssh/config?

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.

Get Shell Drop on the App Store QR code for Shell Drop on the App Store Reading on a computer? Scan the code with your iPhone camera.