Using the SSH Config File

If you are regularly connecting to multiple remote systems via SSH, remembering various IP addresses, usernames, non-standard ports, and command-line options can be challenging or even impossible.

One approach is to create a bash alias for each remote server connection. However, there is a better, more straightforward solution. OpenSSH allows you to set up a per-user configuration file where you can store different SSH options for each remote machine you connect to.

This guide covers the basics of the SSH client configuration file and highlights some of the most common options.

SSH Config File Location #

The OpenSSH client-side configuration file is named config, and resides in the .ssh directory under the user’s home directory. The examples in this guide assume you are using Linux or macOS with an OpenSSH client installed.

This file configures the SSH client, the program you run to connect to other machines. The SSH server uses a separate file, /etc/ssh/sshd_config. To change how your own server accepts connections, see our guide on SSH hardening .

The ~/.ssh directory is created automatically when the user runs the ssh command for the first time. If the directory does not exist on your system, create it with:

mkdir -p ~/.ssh && chmod 700 ~/.ssh

By default, the SSH configuration file may not exist, so you may need to create it using the touch command :

touch ~/.ssh/config

OpenSSH refuses to use the file if other users can write to it. Set the permissions so only your user can read and write it:

chmod 600 ~/.ssh/config

SSH Config File Structure and Patterns #

The SSH config file takes the following structure:

Host hostname1
    SSH_OPTION value
    SSH_OPTION value

Host hostname2
    SSH_OPTION value

Host *
    SSH_OPTION value

The contents of the SSH client config file are organized into stanzas (sections).

Each stanza begins with the Host directive and contains specific SSH options that apply when connecting to matching hosts.

Indentation is not required, but it is recommended because it makes the file easier to read.

Lines beginning with # are treated as comments and ignored by SSH, which makes them useful for documenting aliases or temporarily disabling options.

The Host value can be a single hostname, IP address, or pattern, or a space-separated list of patterns. Each pattern can contain zero or more non-whitespace characters or one of the following pattern specifiers:

• * - Matches zero or more characters. (e.g. Host * matches all hosts, and 192.168.0.* matches hosts in the 192.168.0.0/24 subnet.)
• ? - Matches exactly one character. (e.g. Host 10.10.0.? matches 10.10.0.1 through 10.10.0.9, but not 10.10.0.10.)
• ! - When used at the start of a pattern, it negates the match. (e.g. Host 10.10.0.* !10.10.0.5 matches any host in the 10.10.0.0/24 subnet except 10.10.0.5.)

The SSH client processes the file from top to bottom. If more than one pattern matches, the options from the first matching stanza take precedence. Therefore, more host-specific declarations should be given at the beginning of the file, and more general overrides (like Host *) at the end of the file.

You can find a full list of available SSH options by typing man ssh_config in your terminal or by visiting the ssh_config man page .

The SSH config file is also read by other programs such as scp , sftp , and rsync .

Basic Example #

Normally, when connecting to a remote server via SSH, you would specify the remote user name, hostname, and port. For example, to log in as a user named john to a host called dev.example.com on port 2322 from the command line, you would type:

ssh john@dev.example.com -p 2322

To connect to the server using the same options as provided in the command above by typing ssh dev, add the following lines in your ~/.ssh/config file:

Host dev
    HostName dev.example.com
    User john
    Port 2322

Now, when you type ssh dev, the ssh client will read the configuration file and use the connection details that are specified for the dev host:

ssh dev

Advanced Example: Patterns and Precedence #

This example gives more detail about host patterns and option precedence.

Consider the following example file:

Host targaryen
    HostName 192.168.1.10
    User daenerys
    Port 7654
    IdentityFile ~/.ssh/targaryen.key

Host tyrell
    HostName 192.168.10.20

Host martell
    HostName 192.168.10.50

Host *ell
    user oberyn

Host * !martell
    LogLevel INFO

Host *
    User root
    Compression yes

• When you type ssh targaryen, the SSH client reads the file and applies the options from the first match, which is Host targaryen. Then it checks the next stanzas one by one for a matching pattern. The next matching one is Host * !martell (meaning all hosts except martell), and it will apply the connection option from this stanza. The last definition Host * also matches, but the SSH client will take only the Compression option because the User option is already defined in the Host targaryen stanza.

  The full list of options used when you type ssh targaryen is as follows:

  ini

  HostName 192.168.1.10
  User daenerys
  Port 7654
  IdentityFile ~/.ssh/targaryen.key
  LogLevel INFO
  Compression yes

• When running ssh tyrell, the matching host patterns are: Host tyrell, Host *ell, Host * !martell, and Host *. The options used in this case are:

  ini

  HostName 192.168.10.20
  User oberyn
  LogLevel INFO
  Compression yes

• If you run ssh martell, the matching host patterns are: Host martell, Host *ell and Host *. The options used in this case are:

  ini

  HostName 192.168.10.50
  User oberyn
  Compression yes

• For all other connections, the SSH client will use the options specified in the Host * !martell and Host * sections.

You do not have to work out the matching rules by hand. The -G option prints the options ssh would use for a host and exits without connecting:

ssh -G tyrell

The output lists every option, including the defaults, so it is long. Use grep to show only the values you care about:

ssh -G tyrell | grep -E '^(user|hostname|compression) '

user oberyn
hostname 192.168.10.20
compression yes

The values match the list above. ssh -G prints option names in lowercase.

Overriding Options #

The SSH client reads its configuration in the following precedence order:

1. Options specified from the command line.
2. Options defined in the ~/.ssh/config.
3. Options defined in the system-wide /etc/ssh/ssh_config file.

To override a single option, specify it on the command line. For example, if you have the following definition:

Host dev
    HostName dev.example.com
    User john
    Port 2322

and you want to use all other options but connect as user root instead of john, simply specify the user on the command line:

ssh -o "User=root" dev

The -F (configfile) option allows you to specify an alternative per-user configuration file.

To tell the SSH client to ignore all of the options specified in the SSH configuration file, use:

ssh -F /dev/null user@example.com

Common SSH Config Options #

Here are some of the most useful directives you will reach for regularly.

Keep connections alive

SSH connections drop when there is no traffic for a period of time. To prevent this, configure keepalive packets in a Host * block at the end of your config:

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

ServerAliveInterval sends a keepalive packet every 60 seconds. ServerAliveCountMax closes the connection after 3 unanswered packets.

Specify a private key

If you use different keys for different servers, set IdentityFile per host:

Host github.com
    User git
    IdentityFile ~/.ssh/github_key
    IdentitiesOnly yes

IdentitiesOnly yes tells ssh to use only configured identity and certificate files, including the key set by IdentityFile in this block. Without it, ssh also tries identities offered by your SSH agent or external key providers. The server may close the connection with “Too many authentication failures” before ssh reaches the right key.

Connect through a jump host

ProxyJump routes your connection through an intermediate server. This replaces the older ProxyCommand approach:

Host internal
    HostName 10.0.0.50
    User admin
    ProxyJump jumphost.example.com

Now ssh internal connects through jumphost.example.com automatically.

Enable SSH agent forwarding

When you need to authenticate to a second server from within an SSH session, enable agent forwarding only for the hosts that need it:

Host bastion
    HostName bastion.example.com
    ForwardAgent yes

Avoid setting ForwardAgent yes in a Host * block, as it exposes your SSH agent to every server you connect to.

Split the config into multiple files

As the list of hosts grows, you can move groups of hosts into separate files and load them with the Include directive:

Include ~/.ssh/config.d/*

Host dev
    HostName dev.example.com
    User john

Put the Include line at the top of the file. An Include placed inside a Host block applies only to that block. Create the directory first with mkdir -p ~/.ssh/config.d.

Ubuntu and Debian use the same approach for system-wide settings. The default /etc/ssh/ssh_config includes every .conf file in /etc/ssh/ssh_config.d/.

Quick Reference #

For a printable quick reference, see the SSH cheatsheet .

Troubleshooting #

“Bad owner or permissions” error
OpenSSH accepts a personal config file owned by your account or root, but rejects one owned by another account or writable by the group or others. Restore ownership to your account and set secure permissions with:

sudo chown "$USER":"$(id -gn)" ~/.ssh/config
chmod 600 ~/.ssh/config

The first command sets your account as the owner. The second removes access for the group and others.

Options are not being applied
Run ssh -G alias to see the options ssh actually uses for that host. If a value is wrong, an earlier Host block set it first. Move the specific block above the general one, or check that your Host pattern matches the alias you are using.

“Bad configuration option” error
There is a typo in a directive name. SSH config directives are case-insensitive but must be spelled correctly. Check the directive against man ssh_config.

“Permission denied (publickey)” despite setting IdentityFile
Verify the path in IdentityFile is correct and the key file permissions are 600. You can test which key is being offered with ssh -v alias and look for lines starting with Offering public key.

Config works with ssh but not scp or rsync
Both scp and rsync (over SSH) read ~/.ssh/config. Check that the Host pattern matches the hostname or alias you pass to those commands, not just the alias you use with ssh.

FAQ #

What is the difference between ~/.ssh/config and /etc/ssh/ssh_config?
~/.ssh/config is your personal config. Only your user account reads it. /etc/ssh/ssh_config applies to all users on the system and is managed by the system administrator. Your personal config takes precedence for any options it defines.

Can I have multiple Host entries pointing to the same server?
Yes. You can define multiple stanzas with different aliases that connect to the same HostName, each with different options. For example, one alias can log in as a regular user and another as root.

How do I apply an option to all hosts?
Add a Host * stanza at the end of your config file. Options in Host * apply to every connection but have the lowest precedence. Any host-specific option defined earlier in the file takes priority.

Conclusion #

The SSH config file is the most practical way to manage connections to multiple remote servers. Once your aliases are in place, tools like scp, sftp, and rsync pick them up automatically. To further simplify logins, set up SSH key-based authentication so you can connect without entering a password each time.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 1000+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page