SSH Handbook

Config Customization

For users who frequently connect to multiple servers, customizing the SSH configuration file can dramatically simplify connection management. By configuring SSH options in ~/.ssh/config, it is possible to reduce the need for repetitive command-line options, making connections to complex environments more efficient.

Simplifying Complex SSH Connections

The SSH configuration file allows the specification of host-specific parameters, such as user, port, identity file, and proxy settings, without having to specify them in every connection command. This customization is especially helpful when dealing with multiple jump hosts, non-default ports, or custom authentication mechanisms.

Basic SSH Config File Setup

The SSH configuration file is located in ~/.ssh/config and can contain settings for individual hosts or groups of hosts. Below is an example of a basic configuration for connecting to a remote server:

Host remote-server
    HostName remote-host.com
    User user
    Port 2222
    IdentityFile ~/.ssh/id_rsa

In this example, connecting to remote-server automatically uses the specified hostname, port, and identity file, so the connection command can be simplified:

ssh remote-server

This eliminates the need to specify these options each time, reducing command complexity.

Handling Multiple Hosts

When managing multiple servers, especially those within the same domain or network, wildcard entries can simplify the configuration.

Host *.example.com
    User user
    IdentityFile ~/.ssh/id_rsa

With this configuration, any connection to a host within example.com will automatically use the specified user and identity file.

Using Jump Hosts

For environments where internal servers are only accessible via a jump host (also known as a bastion host), the SSH configuration file can simplify the process by using the ProxyJump directive.

Host internal-server
    HostName internal.example.com
    User user
    ProxyJump user@jump-host.example.com

With this configuration, SSH will automatically connect through the jump host without needing to manually chain commands. This reduces the complexity of the connection string:

ssh internal-server

Grouping Configurations

In more complex environments, grouping configurations for multiple servers can be useful. For example, a group of servers in the same domain can share a base configuration, with additional settings for specific hosts.

Host *.project.local
    User user
    IdentityFile ~/.ssh/id_project_rsa

Host web.project.local
    Port 2222

Host db.project.local
    Port 3306

In this setup, any server within the project.local domain uses the same user and identity file, while specific hosts have customized port settings.

Controlling Timeouts and KeepAlive Settings

SSH configuration also allows for fine-tuning connection behavior, such as controlling timeouts and keeping long-running sessions alive. These settings are useful for environments with unstable connections.

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
  • ServerAliveInterval: Sends a signal to the server every 60 seconds to keep the connection alive.
  • ServerAliveCountMax: Defines how many times the server is allowed to not respond before the connection is terminated.

These settings can prevent SSH sessions from being dropped during periods of network instability.

Using Different Keys for Different Servers

When managing connections to multiple systems that require different SSH keys, the IdentityFile directive allows specifying which key to use for each host.

Host git-server
    HostName git.example.com
    User git
    IdentityFile ~/.ssh/id_rsa_git

Host internal-server
    HostName internal.example.com
    User user
    IdentityFile ~/.ssh/id_rsa_internal

This setup simplifies the process of managing SSH keys for different systems, eliminating the need to manually specify the key with each connection.

Customizing the SSH configuration file offers significant flexibility and efficiency, especially in complex or multi-server environments. With these configurations, connections can be managed more easily, ensuring that SSH remains streamlined even as environments grow in complexity.

← SSH Ecosystem
SSH Configuration File Reference →