The SSH config file: aliases, jump hosts and keys per server

Everything you can pass to ssh on the command line can live in ~/.ssh/config instead, keyed by host. Then ssh db1 replaces ssh -i ~/.ssh/id_ed25519_work -p 2222 -J bastion.example.com [email protected], and scp, rsync, git and your editor’s remote mode all pick up the same settings.

Shape of the file

# ~/.ssh/config  (chmod 600)

Host web1
    HostName web1.example.com
    User deploy

Host db1
    HostName 10.0.5.11
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes
    ProxyJump bastion

Host bastion
    HostName bastion.example.com
    User dominik
    IdentityFile ~/.ssh/id_ed25519_work

Host *.example.com
    User deploy

Host *
    AddKeysToAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Rules that decide what applies:

• A Host line starts a block; the patterns after it are matched against the name you typed (ssh db1), not against HostName. * and ? are wildcards.
• The first value wins. ssh reads the whole file and for each option keeps the first match. So put specific hosts at the top and Host * defaults at the bottom.
• Command-line flags take precedence over the file. /etc/ssh/ssh_config is read after your file, so it only fills in options you did not set.
• Keys are case-insensitive; indentation is only for readability.

Check what ssh will actually use for a host without connecting:

ssh -G db1          # prints every effective option
ssh -v db1          # verbose connection log, including which keys it tries

Options you will use

• HostName: the real address or DNS name. Lets the alias be anything you like.
• User, Port: what you would pass with -l and -p.
• IdentityFile: the private key for this host. Can be repeated. Paths may start with ~.
• IdentitiesOnly yes: offer only the configured key, not every key in the agent. Important when you have several keys: servers disconnect after too many failed key offers (Too many authentication failures), and some services such as GitHub identify you by whichever key is accepted first.
• ProxyJump: connect through another host (a bastion or jump host). Takes an alias from this file or user@host:port; chain several with commas. The command-line equivalent is -J. Prefer it over the older ProxyCommand ssh -W recipe.
• ForwardAgent yes: let the remote host use your local agent, for example to git pull from there. Only enable it per host you trust; root on that host can use your keys while you are connected. ProxyJump does not need it.
• ServerAliveInterval 60 with ServerAliveCountMax 3: send a keep-alive every 60 seconds and give up after 3 missed replies, so idle sessions through NAT and firewalls do not freeze silently.
• AddKeysToAgent yes: load a key into the agent on first use. On macOS add UseKeychain yes to also store the passphrase in the keychain.
• LocalForward 15432 127.0.0.1:5432: a port forward that is set up on every connection, so psql -h 127.0.0.1 -p 15432 on your laptop reaches the database on the server.
• StrictHostKeyChecking: leave at the default ask. accept-new accepts unknown hosts automatically but still refuses changed keys, which is acceptable for throwaway lab VMs. Never set no for real servers.
• Include ~/.ssh/config.d/*: split the file, for example one file per customer. Put Include at the top, since the included options are inserted at that point and the first-match rule applies.

Reusing one connection

Opening a connection involves a handshake and authentication. ControlMaster lets later sessions to the same host ride on the first one, which makes repeated scp, rsync and Ansible runs noticeably faster:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 10m

Create the directory first: mkdir -p ~/.ssh/sockets. %r, %h and %p expand to user, host and port so sockets do not clash. ControlPersist 10m keeps the master open for 10 minutes after the last session closes.

Windows

The built-in OpenSSH client reads C:\Users\you\.ssh\config with the same syntax. Paths in IdentityFile may use ~ as well. The file must not be writable by other users, or it is ignored.

Official documentation

• ssh_config(5)
• ssh(1)