OpenSSH Config File Examples For Linux / Unix Users

How do I create and setup an OpenSSH config file to create shortcuts for servers I frequently access under Linux or Unix desktop operating systems?

We can set up a global or local configuration file for SSH clients can create shortcuts for sshd servers, including advanced ssh client options.
Tutorial details
Difficulty level Intermediate
Root privileges Yes
Requirements OpenSSH client
Est. reading time 7 mintues
You can configure your OpenSSH ssh client using various files as follows to save time and typing frequently used ssh client command-line options such as port, user, hostname, identity-file, and much more to increase your productivity from Linux/macOS or Unix desktop:
My Sample OpenSSH config file
You can configure your OpenSSH ssh client to save typing time for frequently used ssh client command-line options such as port number, user name, hostname/IP address, identity file, and much more. In addition to that it will increase your productivity from Linux/macOS or Unix desktop.

System-wide OpenSSH config file client configuration

  1. /etc/ssh/ssh_config : This files set the default configuration for all users of OpenSSH clients on that desktop/laptop and it must be readable by all users on the system.

User-specific OpenSSH file client configuration

  1. ~/.ssh/config or $HOME/.ssh/config : This is user’s own configuration file which, overrides the settings in the global client configuration file, /etc/ssh/ssh_config.

~/.ssh/config file rules

The rules are as follows to create an ssh config file:

  • You need to edit ~/.ssh/config with a text editor such as vi.
  • One config parameter per line is allowed in the configuration file with the parameter name followed by its value or values. The syntax is:
    config value
    config1 value1 value2
  • You can use an equal sign (=) instead of whitespace between the parameter name and the values.
    config1=value1 value2
  • All empty lines and lines starting with the hash (#) are ignored are ignored.
  • Please note that all values are case-sensitive, but parameter names are not.

Tip : If this is a brand new Linux, macOS/Unix box, or if you have never used ssh before create the ~/.ssh/ directory first using the following syntax:
mkdir -p $HOME/.ssh
chmod 0700 $HOME/.ssh


For demonstration purpose my sample setup is as follows:

  1. Local desktop client – Apple macOS/OS X/Ubuntu Linux.
  2. Remote Unix server – OpenBSD server running latest OpenSSH server.
  3. OpenSSH remote server ip/host: (
  4. Remote OpenSSH server user: nixcraft
  5. OpenSSH dest port: 4242
  6. Local ssh private key file path : /nfs/shared/users/nixcraft/keys/server1/id_rsa

Based upon the above information my ssh command is as follows:
$ ssh -i /nfs/shared/users/nixcraft/keys/server1/id_rsa -p 4242
$ ssh -i /nfs/shared/users/nixcraft/keys/server1/id_rsa -p 4242 -l nixcraft
See how much I need to type. I need to remember the remote hostname/IP, port number, the path to ssh key, username, etc. Too much typing and is not increasing my productivity. But fear not, there is an easy way out.

Using the ssh config file

You can avoid typing all of the ssh command parameters while logging into a remote machine and/or for executing commands on a remote machine. All you have to do is create an ssh config file. Open the Terminal application and create your config file by typing the following command:

## edit file in $HOME dir
vi ~/.ssh/config


## edit file in $HOME dir
vi $HOME/.ssh/config

Add/Append the following config option for a shortcut to server1 as per our sample setup:

Host server1
     User nixcraft
     Port 4242
     IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa

Save and close the file in vi/vim by pressing Esc key, type :w and hit Enter key. To open your new SSH session to by typing the following command:
$ ssh server1

Adding another host

Append the following to your ~/.ssh/config file:

Host nas01
     User root
     IdentityFile ~/.ssh/nas01.key

You can simply type:
$ ssh nas01

Understanding Host Patterns

A pattern for Host directive is nothing but IP address, DNS hostname, or combination of special wildcard characters. For example, ? wildcard that matches exactly one character. On the other hand, * wildcard matches zero or more characters. It allows us to define the usage pattern. For instance, to specify and allow login from laptop.sweet.home, desktop.sweet.home, rpi.sweet.home, and corerouter.sweet.home, I could use the following pattern:

Host *.sweet.home
     User vivek
     IdentityFile ~/.ssh/

The following pattern would match any host in the 192.168.2.[0-9] network range:

Host 192.168.2.?
     User admin
     IdentityFile ~/.ssh/

We can also set a pattern list. It is a comma-separated list of patterns. Patterns within pattern lists may be negated by preceding them with an exclamation mark (!) in your authorized_keys. Here is an example from ~/.ssh/authorized_keys file on the remote server. First, login to the remote box:
$ ssh vivek@
Now edit the file, run:
$ vim ~/.ssh/authorized_keys
Update it as follows:

# Allow login from subnet but not from
from="!,192.168.2.*" ssh-ed25519 my_random_pub_key_here vivek@nixcraft
# Allow login from *.sweet.home but not from router.sweet.home
from="!router.sweet.home,*.sweet.home" ssh-ed25519 my_random_pub_key_here vivek@nixcraft

Save and close the file in vim.

Putting it all together

Here is my sample ~/.ssh/config file that explains and create, design, and evaluate different needs for remote access using ssh client:

### default for all ##
Host *
     ForwardAgent no
     ForwardX11 no
     ForwardX11Trusted yes
     User nixcraft
     Port 22
     Protocol 2
     ServerAliveInterval 60
     ServerAliveCountMax 30
## override as per host ##
Host server1
     User nixcraft
     Port 4242
     IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa
## Home nas server ##
Host nas01
     User root
     IdentityFile ~/.ssh/nas01.key
## Login AWS Cloud ##
Host aws.apache
     User wwwdata
     IdentityFile ~/.ssh/aws.apache.key
## Login to internal lan server at via our public uk office ssh based gateway using ##
## $ ssh ##
Host uk.lan
     User nixcraft
     ProxyCommand  ssh nc %h %p 2> /dev/null
## Our Us Proxy Server ##
## Forward all local port 3128 traffic to port 3128 on the remote server ## 
## $ ssh -f -N  proxyus ##
Host proxyus
    User breakfree
    IdentityFile ~/.ssh/
    LocalForward 3128

Understanding ~/.ssh/config entries

  • Host : Defines for which host or hosts the configuration section applies. The section ends with a new Host section or the end of the file. A single * as a pattern can be used to provide global defaults for all hosts.
  • HostName : Specifies the real host name to log into. Numeric IP addresses are also permitted.
  • User : Defines the username for the SSH connection.
  • IdentityFile : Specifies a file from which the user’s DSA, ECDSA or DSA authentication identity is read. The default is ~/.ssh/identity for protocol version 1, and ~/.ssh/id_dsa, ~/.ssh/id_ecdsa and ~/.ssh/id_rsa for protocol version 2.
  • ProxyCommand : Specifies the command to use to connect to the server. The command string extends to the end of the line, and is executed with the user’s shell. In the command string, any occurrence of %h will be substituted by the host name to connect, %p by the port, and %r by the remote user name. The command can be basically anything, and should read from its standard input and write to its standard output. This directive is useful in conjunction with nc(1) and its proxy support. For example, the following directive would connect via an HTTP proxy at
    ProxyCommand /usr/bin/nc -X connect -x %h %p
  • LocalForward : Specifies that a TCP port on the local machine be forwarded over the secure channel to the specified host and port from the remote machine. The first argument must be [bind_address:]port and the second argument must be host:hostport.
  • Port : Specifies the port number to connect on the remote host.
  • Protocol : Specifies the protocol versions ssh(1) should support in order of preference. The possible values are 1 and 2.
  • ServerAliveInterval : Sets a timeout interval in seconds after which if no data has been received from the server, ssh(1) will send a message through the encrypted channel to request a response from the server. See blogpost “Open SSH Server connection drops out after few or N minutes of inactivity” for more information.
  • ServerAliveCountMax : Sets the number of server alive messages which may be sent without ssh(1) receiving any messages back from the server. If this threshold is reached while server alive messages are being sent, ssh will disconnect from the server, terminating the session.

Speed up ssh session

Multiplexing is nothing but send more than one ssh connection over a single connection. OpenSSH can reuse an existing TCP connection for multiple concurrent SSH sessions. This results into reduction of the overhead of creating new TCP connections. Update your ~/.ssh/config:

Host server1
        ControlPath ~/.ssh/controlmasters/%r@%h:%p
        ControlMaster auto

See “Linux / Unix: OpenSSH Multiplexer To Speed Up OpenSSH Connections” for more info. In this example, I go through one host to reach another server i.e. jump host using ProxyCommand:

## ~/.ssh/config ##
Host internal
  User vivek
  ProxyCommand ssh -W %h:%p
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlMaster auto

For more info see following tutorials:

How to override ssh config file option

The ssh command reads its configuration in the following order:

  1. ssh command line-option
  2. ~/.ssh/config option
  3. /etc/ssh/ssh_config options

Say you have the following options set in ~/.ssh/config:

Host ln.openvpn-sg-vpn1 ln.wireguard-sg-vpn1
     User vivek
     port 22
     IdentityFile ~/.ssh/
     StrictHostKeyChecking no

Now want to use all other options from ~/.ssh/config but to connect using admin user instead of vivek, then:
$ ssh -o "User=admin" ln.openvpn-sg-vpn1
We can specifies an alternative per-user configuration file such as /dev/null to disable ~/.ssh/config too by passing the -F:
$ ssh -F /dev/null admin@
$ ssh -F /dev/null vivek@
$ ssh -F /dev/null -i ~/.ssh/aws/ vivek@

A note about shell aliases (outdated method)

WARNING! This bash shell aliased based setup may work out for you. However, I recommend that you use ~/.ssh/config file for better results in a long run. SSH config file is more advanced and elegant solutions. The alias command only used here for demo purpose and it is here due to historical reasons.

An alias is nothing but shortcut to commands and you can create the alias use the following syntax in your ~/.bashrc file:

## create a new bash shell alias as follow ##
alias server1="ssh -i /nfs/shared/users/nixcraft/keys/server1/id_rsa -p 4242"

Then, to ssh into the server1, instead of typing full ssh -i /nfs/shared/users/nixcraft/keys/server1/id_rsa -p 4242 command, you would only have to type the command ‘server1’ and press the [ENTER] key:
$ server1


This page explained the ssh client configuration file syntax and examples to increase your productivity at Linux, macOS, or Unix shell. See the following resources:

🐧 Get the latest tutorials on Linux, Open Source & DevOps via RSS feed or Weekly email newsletter.

🐧 16 comments so far... add one

CategoryList of Unix and Linux commands
Disk space analyzersdf duf ncdu pydf
File Managementcat cp mkdir tree
FirewallAlpine Awall CentOS 8 OpenSUSE RHEL 8 Ubuntu 16.04 Ubuntu 18.04 Ubuntu 20.04
Modern utilitiesbat exa
Network UtilitiesNetHogs dig host ip nmap
OpenVPNCentOS 7 CentOS 8 Debian 10 Debian 8/9 Ubuntu 18.04 Ubuntu 20.04
Package Managerapk apt
Processes Managementbg chroot cron disown fg glances gtop jobs killall kill pidof pstree pwdx time vtop
Searchingag grep whereis which
User Informationgroups id lastcomm last lid/libuser-lid logname members users whoami who w
WireGuard VPNAlpine CentOS 8 Debian 10 Firewall Ubuntu 20.04
16 comments… add one
  • scott carlson Oct 13, 2013 @ 20:30

    Nice examples…. here is what mine starts with, because I use the control master all the time. Which you can start in the background with “ssh -MNf host”.

    I’ve found that attempting GSSApiAuth slows everything down, so I turn that off, and I’ve picked the order of the ciphers to be faster as well.

    Also with newer versions of ssh, you don’t need netcat anymore for proxying, you can use this line in the host definition instead: “ProxyCommand ssh -W %h:%p”

    Last comment, is that I recommend, using multiple aliases for the host, and include all possible ways you’ll refer to the box. So that if you cut and paste a name, you’ll still get the same settings. As an example, if your DNS search path has, then you might do this: “host web ”

    # ssh -Mnf starbuck sleep 30d
    Host *
    ControlPath ~/.ssh/%l-master-%r@%h:%p
    ControlMaster auto
    ServerAliveInterval 60
    GSSAPIAuthentication no
    Ciphers arcfour256,arcfour128,arcfour,blowfish-cbc,aes128-ctr,aes192-ctr,aes256-ctr,arcfour256,arcfour128,aes128-cbc,3des-cbc,cast128-cbc,aes192-cbc,aes256-cbc,arcfour
    ForwardAgent yes
    LogLevel quiet

  • Just a lurker Jul 9, 2014 @ 15:18

    This is really very nice article, however I would discuss the place of the default config, because of the manual:
    For each parameter, the first obtained value will be used.
    The configuration files contain sections separated by “Host”
    specifications, and that section is only applied for hosts
    that match one of the patterns given in the specification.
    The matched host name is the one given on the command line.

    Since the first obtained value for each parameter is used,
    more host-specific declarations should be given near the
    beginning of the file, and general defaults at the end.

    …so I have my defaults at the end.

  • Olivier Mengué (DOLMEN) Jul 14, 2014 @ 7:07

    For Github you may be interested in a tool I wrote that completely automates this setup using the most secure settings: github-keygen

  • SAFDAR Aug 7, 2015 @ 20:44

    Is there a limit on number of IdentityFile we can use in config file under one block?

    Host server1
    User nixcraft
    Port 4242
    IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa
    IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa1
    IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa2
    IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa3
    IdentityFile /nfs/shared/users/nixcraft/keys/server1/id_rsa10

  • Amit kumar Jul 28, 2016 @ 16:56

    issue get resolved after saving the cipher values in /etc/ssh/ssh_config file..
    Really thanks for this article.

  • walee Jul 29, 2016 @ 15:28

    I have a problem win I enable public key on fedora 23 or centos 7 I receive this wrong “Permission denied (publickey,gssapi-keyex,gssapi-with-mic).

  • Chris Duong Dec 30, 2016 @ 4:43

    Is there any use case for using “Include Statement”. I had done this, the file is read but the hostname does not work.

  • Nurd Mar 10, 2017 @ 17:50

    Thanks! Useful article.

  • dedRabbitt Apr 22, 2017 @ 15:52

    Very nice!

  • Bill Oct 10, 2017 @ 8:57

    This is one of the most useful, simple and informative pages I’ve ever read in the technical context! :)

  • John Dec 1, 2017 @ 0:22

    Thanks so much, I totally agree with Bill–superb post.

  • Andrew McGlashan Aug 18, 2020 @ 9:03

    There is a problem with the “putting it all together” example.

    As you can see from the following, if you define something, then it cannot be redefined later. You need to “*” grouping at the end of the file to catch things that aren’t yet defined for a “Host” entry.
    Two example config files and attempts to use them shown below demonstrate this fact.

    $ cat /tmp/configx

    Host *
    	Port 24
    	Protocol 2
    Host sadsack
    	Port 333
    	Hostname aaa

    $ ssh -F /tmp/configx sadsack
    ssh: connect to host aaa port 24: Connection refused

    $ cat /tmp/configy

    Host sadsack
    	Port 333
    	Hostname aaa
    Host *
    	Port 24
    	Protocol 2
    $ ssh -F /tmp/configy sadsack
    ssh: connect to host aaa port 333: Connection refused
  • Dietmar (in Western Germany) Oct 18, 2020 @ 11:33

    Great page! The whole site is of outstanding quality an reliability!!
    One demand about ssh config file is not covered:
    What, if I want to “land” in a particulart directory? Can you cover this question?
    The only solution I found elsewhere:

    sudo vim .ssh/config

            ## needs both!!:
            RequestTTY yes
            RemoteCommand  cd /srv/terra-daten/; exec $SHELL

    May be you find a better solution?
    Much appreciate your work!

  • ömer Nov 22, 2020 @ 11:08

    Thank you in advance.
    My problem is that I couldn’t “Save and close the file”. After Add/append config, how can I exit that screen?

Leave a Reply

Your email address will not be published.

Use HTML <pre>...</pre> for code samples. Still have questions? Post it on our forum