Understanding the SSH Config File: Key Parameters and Options for Efficient Host Configuration

The SSH config file (~/.ssh/config) allows users to define preferences and settings for different SSH connections, streamlining remote access and improving overall security and convenience. By specifying various configuration options for individual hosts, users can avoid repeatedly entering lengthy commands or parameters every time they connect to remote systems.

This article will walk you through the most useful parameters in the SSH config file, enabling you to configure connections for various hosts efficiently.

Location of the SSH Config File

The SSH configuration file is typically located in the ~/.ssh/config directory on Unix-based systems (Linux, macOS, etc.). If the file doesn’t already exist, you can create it manually. You can also specify system-wide SSH configurations in /etc/ssh/ssh_config.

~/.ssh/config

Basic Structure of the SSH Config File

The configuration file is organized into sections, each beginning with the Host keyword, followed by the hostname or pattern to match the specific host. Each host section contains various options that define the behavior of the connection.

Host <hostname_pattern>
    OptionName option_value

You can use wildcards (*) to match multiple hosts. For example:

Host *.example.com
    User myuser
    Port 22

Most Useful SSH Config Options and Parameters

Here’s a rundown of the most commonly used parameters and options that can be added to your SSH config file to improve your SSH experience:

Host: The Host directive specifies the alias or pattern to match the host you want to configure. You can match specific hostnames or use wildcards.

Host server1
    HostName 192.168.1.100
    User myuser

HostName: This parameter defines the actual remote host or IP address you wish to connect to. It is helpful when using a simple alias under Host to refer to the actual hostname.

Host webserver
    HostName webserver.example.com
    User admin

User: This option defines the username to use when connecting to the remote host. If you don’t specify it, SSH defaults to your current local username.

Host remote_host
    User johndoe

Port: The Port option specifies the port number for the SSH connection. The default SSH port is 22, but it is often customized for security purposes.

Host myserver
    Port 2222

IdentityFile: This directive allows you to specify the private key file to use for authentication. This is particularly useful if you have multiple keys and want to use different keys for different hosts.

Host myserver
    IdentityFile ~/.ssh/my_key

ForwardAgent: The ForwardAgent option controls whether the SSH agent should be forwarded to the remote server. This is useful if you need to use your local SSH keys on a remote server without having to manually copy them over.

Host jump-host
    ForwardAgent yes

ForwardX11 and ForwardX11Trusted: These options enable or disable X11 forwarding, which allows you to run graphical applications over SSH. Setting ForwardX11Trusted to yes ensures that the X11 connection is trusted.

Host graphics-server
    ForwardX11 yes
    ForwardX11Trusted yes

ProxyCommand: The ProxyCommand option defines how to connect to a host via an intermediary host (jump host). This is particularly useful when you need to go through a gateway to reach the target server.

Host target-server
    ProxyCommand ssh -q -W %h:%p gateway-server

Compression: The Compression option enables or disables compression of the data sent over the SSH connection. This can be helpful when working with slower network connections.

Host myserver
    Compression yes

LogLevel: The LogLevel option allows you to control the verbosity of SSH logs. This is particularly helpful for debugging connections.

Host *
    LogLevel DEBUG

LocalForward and RemoteForward: The LocalForward and RemoteForward options enable port forwarding. You can use them to forward local or remote ports over the SSH connection, allowing you to securely access services on remote machines.

Host remote-db
    LocalForward 3306 localhost:3306
    RemoteForward 6000 localhost:80

ConnectionAttempts: The ConnectionAttempts option specifies the number of times SSH will attempt to connect before giving up.

Host myhost
    ConnectionAttempts 3

ServerAliveInterval and ServerAliveCountMax: These options help you keep an SSH session alive by sending periodic requests to the server. The ServerAliveInterval defines the time (in seconds) between each request, and ServerAliveCountMax specifies the number of allowed failures before disconnecting.

Host server1
    ServerAliveInterval 60
    ServerAliveCountMax 3

Practical examples

Example 1- Basics

Host optimus
    HostName optimus.com

Host megatron
    HostName megatron.com

# common/sherde parameter
Host * 
    Compression yes
    User bt
    LogLevel INFO

To use this configuration, simply run the ssh command with the alias of the host defined in your config file.

ssh optimus 
ssh megatron

Example 2- Jump server

# Configuration for the jump server
Host jumpserver
  HostName 192.168.1.114        # Jump server IP or hostname
  User pi                       # SSH user for the jump server
  IdentityFile ~/.ssh/id_rsa    # Your SSH key for jump server (if needed)

# Configuration for the target server, using the jump server
Host targetserver
  HostName 192.168.1.62         # Target server IP or hostname
  User pi                       # SSH user for the target server
  ProxyJump jumpserver          # Use the jump server defined above
  IdentityFile ~/.ssh/id_ecdsa  # Optional: Use a specific SSH key for the target server

Example 3- Local tunnel

Basic

Host my-remote-host
    HostName example.com
    User myusername
    LocalForward 8080 127.0.0.1:80   # HTTP traffic from local 8080 to remote 80
    LocalForward 3306 127.0.0.1:3306 # MySQL traffic from local 3306 to remote 3306

Advanced : if you want to run ssh session in background

Host my-remote-host
    HostName example.com
    User myusername
    LocalForward 8080 127.0.0.1:80
    LocalForward 3306 127.0.0.1:3306
    RequestTTY no
    ExitOnForwardFailure yes
    -N -f
    
#-N: If you only want to establish the tunnel without actually opening a shell session, you can add the -N option to the Host entry.
# -f: To have SSH run in the background, add -f (useful for automatic port forwarding in scripts).

Example 4- Reverse ssh

Host my-remote-host
    HostName example.com
    User myusername
    RemoteForward 8080 127.0.0.1:80
    RemoteForward 3306 127.0.0.1:3306 # Forward remote 3306 to local 3306

Advanced : if you want to run ssh session in background

Host my-remote-host
    HostName example.com
    User myusername
    RemoteForward 8080 127.0.0.1:80
    RequestTTY no
    -N -f

Conclusion

The SSH config file is a powerful tool that can help you manage connections to various remote systems, saving you time and effort while ensuring secure and efficient access. By utilizing key parameters such as Host, User, Port, and IdentityFile, along with advanced options like ProxyCommand and Compression, you can configure an SSH environment tailored to your needs. These settings allow you to automate and simplify connections, making remote administration and development tasks more convenient.