How to Use the SSH Config File

The SSH config file lets you save hostnames, usernames, ports, private keys, jump hosts, and connection options for the OpenSSH client. Instead of typing a long command every time, you can connect with a short alias such as ssh production.

This guide explains how to create ~/.ssh/config, use several keys, organise multiple servers, check the effective configuration, and solve common permission and matching problems.

SSH client config versus SSH server config

These files have different jobs:

• ~/.ssh/config: personal client settings for the current user.
• /etc/ssh/ssh_config: system-wide client defaults.
• /etc/ssh/sshd_config: configuration for the SSH server daemon.

This article covers client configuration. Editing ~/.ssh/config does not change how the remote SSH server listens or authenticates users.

Create the SSH config file

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

Open it with your preferred text editor:

nano ~/.ssh/config

The file is plain text. Each destination normally begins with a Host line followed by indented options.

Create your first SSH host alias

Host production
    HostName 203.0.113.10
    User deploy
    Port 22

Connect with:

ssh production

The alias production exists only in your SSH client configuration. HostName is the real DNS name or IP address.

Use a specific private key

Host production
    HostName server.example.com
    User deploy
    IdentityFile ~/.ssh/production_ed25519
    IdentitiesOnly yes

IdentityFile selects a key. IdentitiesOnly yes tells SSH to offer only configured identities instead of also trying every key available through the authentication agent. This helps avoid “too many authentication failures.”

Protect the private key:

chmod 600 ~/.ssh/production_ed25519

For key creation and server installation, follow our SSH key authentication guide.

Configure a custom SSH port

Host production
    HostName server.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/production_ed25519

This replaces repeated use of ssh -p 2222. The server and firewalls must already accept the port. See our guide to changing an SSH port safely.

Configure several SSH servers

Host web-prod
    HostName web1.example.com
    User deploy
    IdentityFile ~/.ssh/work_ed25519

Host db-prod
    HostName 10.0.20.15
    User database-admin
    IdentityFile ~/.ssh/work_ed25519

Host personal-vps
    HostName vps.example.net
    User ravi
    IdentityFile ~/.ssh/personal_ed25519

Connect using the alias from each Host line:

ssh web-prod
ssh db-prod
ssh personal-vps

The same aliases work with many OpenSSH tools:

scp report.txt web-prod:/tmp/
sftp web-prod
rsync -av project/ web-prod:/var/www/project/

Use wildcard defaults

Host *.example.com
    User deploy
    IdentityFile ~/.ssh/work_ed25519
    IdentitiesOnly yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

This block matches destination names ending in .example.com. A final general block can provide broad defaults:

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    HashKnownHosts yes

OpenSSH normally uses the first value obtained for each option. Put specific host rules before broad wildcard rules so the intended value is selected.

Understand matching and precedence

The client reads configuration from these sources:

1. Command-line options.
2. The user’s ~/.ssh/config.
3. The system-wide /etc/ssh/ssh_config.

Because the first obtained value generally wins, organise host-specific entries first and defaults later. A single destination can match more than one Host block.

Check the effective SSH configuration

ssh -G production

This prints the final client settings without starting the normal interactive login. Filter important values:

ssh -G production | grep -E '^(hostname|user|port|identityfile|proxyjump) '

Use this before assuming a block is ignored.

Debug an SSH connection

ssh -v production

Use -vv or -vvv for more detail. Debug output can reveal selected configuration files, resolved hostnames, offered keys, and authentication methods. Review it before sharing because it may contain usernames, paths, addresses, and other infrastructure details.

Connect through a jump host

A bastion or jump host can provide controlled access to a private server:

Host bastion
    HostName bastion.example.com
    User ops
    IdentityFile ~/.ssh/bastion_ed25519

Host private-db
    HostName 10.0.20.15
    User database-admin
    IdentityFile ~/.ssh/database_ed25519
    ProxyJump bastion

Then run:

ssh private-db

The destination and jump host can have different users, keys, and ports. Configure both aliases separately.

Use multiple jump hosts

Host deep-server
    HostName 10.30.0.25
    User admin
    ProxyJump gateway-one,gateway-two

OpenSSH visits the comma-separated proxies in order. Keep the chain as simple as the network design allows.

Include separate SSH config files

Split work and personal hosts into smaller files:

Include ~/.ssh/config.d/work.conf
Include ~/.ssh/config.d/personal.conf

Create and protect the directory:

mkdir -p ~/.ssh/config.d
chmod 700 ~/.ssh/config.d
chmod 600 ~/.ssh/config.d/*.conf

Include placement affects which value is found first. Check the result with ssh -G alias.

Use local port forwarding

Host database-tunnel
    HostName bastion.example.com
    User ops
    LocalForward 127.0.0.1:3307 10.0.20.15:3306
    ExitOnForwardFailure yes
    SessionType none

Connecting to this alias forwards local port 3307 to the private database through the SSH server. Bind to 127.0.0.1 unless other local machines genuinely need access. Protect the remote service separately with its own authentication and network controls.

Keep idle SSH connections alive

Host production
    ServerAliveInterval 60
    ServerAliveCountMax 3

The client sends a message after 60 seconds without server data and disconnects after three unanswered messages. This can help on unstable or stateful networks, but it does not preserve a running terminal job after a disconnection. Use tmux or screen for persistent remote sessions.

Reuse SSH connections carefully

Host *.example.com
    ControlMaster auto
    ControlPath ~/.ssh/control-%C
    ControlPersist 5m

Connection multiplexing can make repeated SSH, SCP, and SFTP sessions faster. Protect the control-socket directory and understand that a reusable authenticated connection remains available for the configured persistence time.

Do not disable host-key checking

Avoid configurations such as:

StrictHostKeyChecking no
UserKnownHostsFile /dev/null

They remove protection against connecting to an unexpected or impersonated server. When a host key legitimately changes, verify the new fingerprint through a trusted channel before updating known_hosts.

Common SSH config problems

Bad owner or permissions

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/private_key

Make sure the files belong to the user running SSH.

The alias is ignored

Run ssh -G alias and ssh -v alias. Check the spelling, block order, wildcard matches, and whether you are running SSH as a different user with another home directory.

Too many authentication failures

The agent may be offering many keys before the correct one. Set the intended IdentityFile and IdentitiesOnly yes for that host.

Could not resolve hostname

Confirm that HostName is a valid DNS name or address. The alias belongs on Host; the actual destination belongs on HostName.

Configuration option has no effect

An earlier matching block may already have supplied the value. Remember the first-value rule and inspect the effective output with ssh -G.

Complete example SSH config

Host web-prod
    HostName web1.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/work_ed25519
    IdentitiesOnly yes

Host bastion
    HostName bastion.example.com
    User ops
    IdentityFile ~/.ssh/bastion_ed25519
    IdentitiesOnly yes

Host private-db
    HostName 10.0.20.15
    User database-admin
    IdentityFile ~/.ssh/database_ed25519
    IdentitiesOnly yes
    ProxyJump bastion

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    HashKnownHosts yes

Frequently asked questions

Where is the SSH config file?

The personal OpenSSH client file is ~/.ssh/config. System-wide client defaults are normally in /etc/ssh/ssh_config.

Do I need to restart SSH after editing ~/.ssh/config?

No. New client connections read the file when they start. This file does not configure the SSH server daemon.

Can I use an IP address in HostName?

Yes. The Host alias can be memorable while HostName contains an IP address.

How do I test which key SSH will use?

Check ssh -G alias for configured identity files, then use ssh -v alias to see which keys are offered during a real connection.

Official references

• OpenSSH ssh_config manual
• Linux ssh_config manual page
• Ubuntu Server OpenSSH documentation

A well-organised SSH config file reduces typing and prevents mistakes across multiple servers. Start with a host alias, username, port, and key; add advanced options only when they solve a clear connection or network requirement.