Configure SSH on Linux for your servers without retyping everything

When managing multiple machines, the same SSH options quickly end up in history: user, port, private key, and sometimes a jump. The ~/.ssh/config file replaces this endless line with a short name, for example, ssh preprod.

You do not need to modify the server. This configuration lives on your workstation and tells the OpenSSH client how to connect to each machine. It primarily prevents you from using the wrong key or port when multiple environments look similar.

Create an entry for each server

Create the folder if it does not exist, then open the configuration file:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/config

Then add a block for each machine. Here, preprod is just a local alias. Replace the address, account, port, and key path with your values.

Host preprod
    HostName 192.0.2.44
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_preprod
    IdentitiesOnly yes

You will then be able to launch ssh preprod. HostName contains the real DNS name or IP address, User the remote account, and Port the SSH port. IdentityFile selects the expected private key. With IdentitiesOnly yes, the client does not propose all the keys loaded by your SSH agent, which avoids unnecessary attempts on a server that limits authentications.

If you are already using a key, first check that it is properly protected. A private key should not be readable by other accounts on your workstation:

chmod 600 ~/.ssh/id_ed25519_preprod
chmod 600 ~/.ssh/config

The guide for generating an SSH key on Ubuntu covers how to create the key pair. Never copy a private key to the server. Only the public key belongs in ~/.ssh/authorized_keys on the remote side.

Add common settings at the end of the file

A config file can contain multiple Host blocks. The OpenSSH client retains the first value found for most options. Therefore, place the most specific servers at the top and general values at the bottom.

Host production
    HostName prod.example.net
    User deploy
    IdentityFile ~/.ssh/id_ed25519_production
    IdentitiesOnly yes

Host backup
    HostName backup.example.net
    User backup
    Port 2201
    IdentityFile ~/.ssh/id_ed25519_backup
    IdentitiesOnly yes

Host *
    ServerAliveInterval 30
    ServerAliveCountMax 3

The Host * block applies to all aliases. It is suitable for truly common settings, here the periodic sending of a signal to detect a frozen connection. Avoid placing a key or a user here if your servers do not all use the same account.

You can also group hosts that follow the same rule, with a pattern such as Host *.intra. Keep exceptions above this block. An ambiguous alias or a general rule placed too early often produces surprising behavior.

Check the configuration before connecting

The following command displays the final calculated configuration for an alias, without opening a session. It is very useful after a modification:

ssh -G preprod | grep -E '^(hostname|user|port|identityfile|identitiesonly) '

Check that hostname, user, and port correctly correspond to the targeted machine. Also look at the returned path for identityfile. If you just moved a key, SSH may still point to the old file.

Then, perform a simple test:

ssh preprod
ssh -v preprod

The -v option displays the connection steps and the configuration files read. Do not publish this output as is in a ticket or chat: it may reveal your hostnames, accounts, and local paths.

When the config file is not enough

An SSH alias solves the repetition of options. It does not fix a server that refuses your key, a closed port, or a modified host fingerprint. If authentication keeps asking for your passphrase, use ssh-agent instead of removing the passphrase from the key.

To reach an internal service through a bastion, keep a separate entry with ProxyJump and test it separately. The SSH tunnel addresses another need: it transports a local or remote port; it does not replace the configuration of a host.

Protect ~/.ssh with chmod 700 ~/.ssh.
Protect the config file and each private key with chmod 600.
Check the alias with ssh -G alias_name before a first connection.
Test each new server with its alias, then keep common options in a Host * block placed at the bottom of the file.

The official documentation ssh_config(5) details each directive. Take two minutes to review the output of ssh -G before using an alias on a production machine: it’s faster than searching for why SSH chose the wrong key.