SSH config file: examples for ~/.ssh/config

The file is plain text with no extension, and it doesn't exist until you create it. Don't confuse it with /etc/ssh/sshd_config (with a d), which is the server's settings.

1. 1

   Step 1: Create the file

   # Linux and macOS
   mkdir -p ~/.ssh && chmod 700 ~/.ssh
   touch ~/.ssh/config && chmod 600 ~/.ssh/config
   nano ~/.ssh/config
   
   # Windows PowerShell
   New-Item -ItemType Directory -Force $env:USERPROFILE\.ssh | Out-Null
   if (-not (Test-Path $env:USERPROFILE\.ssh\config)) { New-Item -ItemType File $env:USERPROFILE\.ssh\config | Out-Null }
   notepad $env:USERPROFILE\.ssh\config

   On Windows, make sure the file is called config, not config.txt: ssh ignores the second. Creating it first, as above, stops Notepad adding the extension.

2. 2

   Step 2: Add a Host entry for a server

   Host web
       HostName 203.0.113.10
       User deploy
       Port 2222
       IdentityFile ~/.ssh/id_ed25519
       IdentitiesOnly yes

   Host is the name you type, HostName the real address, then the user, the port and the key. The indenting is only for reading, and lines starting with # are comments. Save the file.

3. 3

   Step 3: Check what ssh will use

   ssh -G web prints every setting ssh would use for web, without connecting. Look for the hostname, user, port and identityfile lines.

4. 4

   Step 4: Connect by its short name

   ssh web connects. sftp web and scp file.txt web:/tmp/ use the same settings (the SFTP guide has the file transfer commands). The server itself has to run SSH, of course: here's how to enable SSH on Ubuntu.

Several servers with shared settings

Host web-01 web-02
    User deploy
    IdentityFile ~/.ssh/id_ed25519

Host web-01
    HostName 203.0.113.11

Host web-02
    HostName 203.0.113.12

Every block whose Host matches applies, so web-01 gets its user and key from the first block and its address from the second.

A whole group with a wildcard

Host *.lab.example.com
    User admin
    IdentityFile ~/.ssh/lab_ed25519

A server behind a jump host (ProxyJump)

Host bastion
    HostName bastion.example.com
    User admin

Host db
    HostName 10.0.0.5
    User admin
    ProxyJump bastion

ssh db signs in to the bastion first and reaches 10.0.0.5 from there, the same as ssh -J bastion admin@10.0.0.5.

A port forward that opens with the connection

Host db-tunnel
    HostName db.example.com
    User admin
    LocalForward 5433 localhost:5432

While ssh db-tunnel is connected, port 5433 on your computer reaches the database on the server. See what an SSH tunnel is for the other kinds of forward.

Defaults for every server (put this last)

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    AddKeysToAgent yes

Keep-alives stop a quiet session from being dropped by a router or firewall. AddKeysToAgent hands your key to ssh-agent after you first type its passphrase; the SSH keys guide explains the agent.

An old device that only offers ssh-rsa

Host old-switch
    HostName 192.168.1.2
    User admin
    HostKeyAlgorithms +ssh-rsa
    PubkeyAcceptedAlgorithms +ssh-rsa

Recent OpenSSH versions refuse the old SHA-1 ssh-rsa signatures by default, so connecting to old switches, routers or NAS boxes can fail with no matching host key type found. Their offer: ssh-rsa. These two lines allow it for that one device only (the second is only needed if you sign in to it with an RSA key). Versions of ssh older than 8.5 don't know PubkeyAcceptedAlgorithms and stop with "Bad configuration option"; they still accept ssh-rsa, so leave both lines out there. Updating the device is the better fix when one exists; the fix for no matching host key type found covers the related key exchange and cipher errors too.

• The first value wins. ssh goes through the file from the top, and for each setting keeps the first value it finds in a matching block. So put specific hosts first and Host * at the end.
• Settings on the command line come first. ssh -p 22 web uses port 22 whatever the file says.
• Check the result with ssh -G. It shows the settings after all of these rules, so it settles any doubt.
• Split it up with Include. Include ~/.ssh/config.d/* near the top reads more files, handy for one file per project.
• Keep it private. ssh refuses a config file other users can write to ("Bad owner or permissions"): chmod 600 ~/.ssh/config.

man ssh_config on Linux or macOS lists every keyword. Most people only ever need the first five, plus Port when a server doesn't use 22.

If you'd like your servers in a list with tabs and a file manager, the RemoteAccessApp SSH client can import the config file you already have:

1. 1

   Step 1: Open Import

   In the Console, open Connections, then Import on the Hosts tab.

2. 2

   Step 2: Read your SSH config

   Import from this PC… (on Linux, Import from this computer…) reads ~/.ssh/config. To use another file, choose your SSH config under Import from file, or Choose a file….

3. 3

   Step 3: Check the preview and import

   Each named Host becomes a saved SSH host with its address, user, port and key file. ProxyJump becomes a jump host and LocalForward, RemoteForward and DynamicForward become port forwards. Wildcard entries and Match blocks are left out. You see the list before anything is added, and passwords never come in.