Use the SSH config file to save hosts and shortcuts

Save every server's address, user, port and key in ~/.ssh/config so you can connect with a short name, share settings with wildcards and avoid key errors with IdentitiesOnly, on Windows, macOS and Linux.

  • Intermediate
  • Linux VPS
  • 4 min read

By RunRacks Team · Published

Typing ssh -i ~/.ssh/client_key -p 2222 [email protected] every time is slow and easy to get wrong. The SSH client config file lets you give each server a short name and store its address, user, port and key once. After that, ssh web is all you type, and the same shortcut works for scp, sftp, rsync, Git and VS Code.

Before you start

Where the file lives

The per-user config file is:

  • Linux and macOS: ~/.ssh/config
  • Windows: C:\Users\<you>\.ssh\config (no file extension)

Create it if it does not exist. On Linux and macOS:

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

On Windows, create it in Notepad and make sure it is not saved as config.txt. In the save dialog, set Save as type to All files.

Your first Host entry

Each block starts with Host followed by the short name you want to type. The indented lines below it apply to that name:

Text
Host web
    HostName 203.0.113.10
    User deploy
    Port 22
    IdentityFile ~/.ssh/id_ed25519
  • Host: the alias you type. It can be anything without spaces.
  • HostName: the real IP address or domain name.
  • User: the login name on the server.
  • Port: the SSH port. Leave it out for the default 22.
  • IdentityFile: the private key to use. ~ works on Windows too.

Now connect with:

Terminal
ssh web

The alias also works with other tools:

Terminal
scp site.tar.gz web:/home/deploy/
rsync -av ./public/ web:/var/www/example.com/
sftp web

Several servers

Add one block per server. A blank line between blocks keeps it readable:

Text
Host web
    HostName 203.0.113.10
    User deploy

Host db
    HostName 198.51.100.20
    User admin
    Port 2222
    IdentityFile ~/.ssh/db_ed25519

A Host line can list several aliases, for example Host web web1 shop.

Wildcards and shared defaults

Patterns let one block apply to many hosts:

  • * matches any text, ? matches one character.
  • ! excludes a pattern.
Text
Host *.example.com
    User deploy
    IdentityFile ~/.ssh/work_ed25519

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

Order matters. For each setting, SSH uses the first value it finds, reading the file top to bottom. Put specific hosts first and the general Host * block at the end, or its values will win over your specific ones.

ServerAliveInterval 60 sends a small keepalive every minute, which stops idle sessions being dropped by routers and firewalls.

IdentitiesOnly: stop "too many authentication failures"

If you have several keys loaded in an SSH agent, the client may offer every one of them before the one in IdentityFile. Servers usually allow only a few attempts, so you get:

Text
Received disconnect from 203.0.113.10 port 22:2: Too many authentication failures

IdentitiesOnly yes tells SSH to offer only the key named in the config:

Text
Host db
    HostName 198.51.100.20
    User admin
    IdentityFile ~/.ssh/db_ed25519
    IdentitiesOnly yes

For more on juggling keys, see Manage several SSH keys.

Other useful options

  • LocalForward 8080 127.0.0.1:80: open a tunnel every time you connect. See SSH local port forwarding.
  • ProxyJump bastion: reach a server through another one.
  • Compression yes: can help on slow links.
  • Include ~/.ssh/config.d/*: split a long config into several files. Put the Include line near the top.

Check the full list with man ssh_config.

Check it works

Ask SSH to show the final settings it would use for an alias, without connecting:

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

You should see the values from your block. Then connect with verbose output to confirm the right key is used:

Terminal
ssh -v web

Look for a line like Offering public key: /home/you/.ssh/id_ed25519.

Troubleshooting

  • `Bad owner or permissions on ~/.ssh/config`: run chmod 600 ~/.ssh/config on Linux or macOS. On Windows, remove other users from the file's Properties → Security list.
  • `Could not resolve hostname web`: the alias is not being read. Check the file name (no .txt), its location, and spelling of the Host line.
  • The wrong user or port is used: an earlier block, often Host *, set it first. Move general blocks to the end.
  • `Bad configuration option` on one machine only: some options are platform-specific, such as UseKeychain on macOS. Add IgnoreUnknown UseKeychain at the top of the file to share it across systems.

Next steps

  • Edit server files in your editor using your aliases: VS Code Remote-SSH.
  • Compare plans for your next server on Linux VPS.

Was this guide helpful?

Still stuck?

Ask RunRacks AI for a quick answer, or open a ticket and our team will take a look at your server.

Linux VPS

Deploy a Node.js app with PM2 behind Nginx

Install a Node.js LTS release, keep your app running with PM2 across crashes and reboots, and serve it through Nginx with HTTPS.

  • Intermediate
  • Linux VPS
  • 3 min read

Linux VPS

Create an SFTP-only user limited to one folder

Give someone file access over SFTP without a shell, locked inside one folder. Configure internal-sftp with a Match block, set the chroot ownership right and test with WinSCP.

  • Advanced
  • Linux VPS
  • 5 min read