Streamlining Your Connections: Mastering the SSH Config File

Tags: SSH Configuration Linux macOS DevOps SysAdmin Security Tutorial SSH Keys

If you frequently connect to multiple remote servers using SSH, you probably find yourself typing the same usernames, IP addresses, ports, and options repeatedly. Remembering specific key files for different hosts can also be a hassle. Thankfully, the SSH client has a configuration file that simplifies your workflow.

This guide explores the SSH config file (typically ~/.ssh/config), how to set it up, common use cases, and related security practices like SSH key management and disabling password authentication.

What is the SSH Config File?

The SSH config file allows you to define aliases and specify connection parameters for different remote hosts. Instead of typing ssh [email protected] -p 2222 -i ~/.ssh/special_key, you could potentially just type ssh myserver, letting the config file handle the rest.

Locating and Creating the Config File

The user-specific SSH configuration file resides in the .ssh directory within your home directory.

  1. Ensure the .ssh directory exists and has the correct permissions: SSH is picky about permissions for security reasons. The directory should only be accessible by you. 
    mkdir -p ~/.ssh
chmod 700 ~/.ssh
  2. Create the config file if it doesn’t exist: 
    touch ~/.ssh/config
    You might also need to set permissions on the config file itself, although chmod 600 (read/write for owner only) is common practice for SSH files, 644 is often sufficient for the config file.

Essential Prerequisite: SSH Keys

While you can use the config file with password authentication, its real power shines when combined with SSH keys for secure, passwordless login.

  1. Generate a new SSH Key Pair (if you don’t have one): This creates a private key (keep it secret!) and a public key (share it).

    # -t rsa: Type of key (RSA is common)
# -b 4096: Key strength in bits (4096 is strong)
# -C "[email protected]": A comment, often your email
ssh-keygen -t rsa -b 4096 -C "[email protected]"

    Follow the prompts. It’s highly recommended to protect your private key with a strong passphrase.

  2. Copy Your Public Key to the Remote Server: This authorizes your key to log in to the specified user account on the server.

    • Method 1: Using ssh-copy-id (Recommended if available)

      ssh-copy-id remote_username@server_ip_address

      This utility handles creating the directory and file with the correct permissions on the remote server.

    • Method 2: Manual Copy (If ssh-copy-id is not available)

      cat ~/.ssh/id_rsa.pub | ssh remote_username@server_ip_address "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

      This command pipes your public key content (cat) over SSH, creates the .ssh directory on the remote server if needed, ensures correct directory permissions (chmod 700), appends the key to the authorized_keys file, and sets the correct file permissions (chmod 600).

  3. Test Login: You should now be able to log in without a password (though you might be prompted for your SSH key passphrase if you set one):

    ssh remote_username@server_ip_address

SSH Config File Structure and Common Options

The ~/.ssh/config file uses a simple structure based on Host blocks. Each block defines settings for a specific host alias or pattern.

# Settings for a specific server, aliased as 'webserver'
Host webserver
    HostName 198.51.100.10   # The actual IP or domain name
    User deploy_user         # Default user for this host
    Port 2222                # Custom SSH port (if not default 22)
    IdentityFile ~/.ssh/webserver_key # Use a specific private key

# Settings for another server
Host dbserver
    HostName db.example.com
    User admin
    IdentityFile ~/.ssh/admin_key

# Default settings for ALL hosts (*) that don't match a specific block above
Host *
    # Example: Send keepalives to prevent disconnects
    ServerAliveInterval 60
    # Example: Use compression
    Compression yes
    # Example: Default user for any other host
    # User default_user

Key Options:

  • Host: Defines the start of a block. The value can be an alias (like webserver) or a pattern (like *.example.com, or * for all hosts).
  • HostName: The actual hostname or IP address to connect to.
  • User: The username to use for the connection.
  • Port: The port number the SSH server is listening on (defaults to 22).
  • IdentityFile: Specifies the path to the private SSH key file to use for authentication. Essential if you use different keys for different hosts.
  • ServerAliveInterval, ServerAliveCountMax: Help keep connections alive (see the Port Forwarding article for details).
  • Compression: Can speed up connections on slow networks (yes/no).

You can find a full list of all available options by typing man ssh_config in your terminal or searching online for the ssh_config man page.

Now, instead of complex commands, you can simply use:

ssh webserver  # Connects using [email protected]:2222 with webserver_key
ssh dbserver   # Connects using [email protected] with admin_key

Configuration Precedence

It’s important to know how SSH decides which option value to use if it’s defined in multiple places. The order of precedence is:

  1. Command-line options: Flags like -p, -l, -i passed directly to the ssh command always override configuration files. (ssh -p 2223 webserver would use port 2223, ignoring the Port 2222 in the config file for that connection).
  2. User’s config file (~/.ssh/config): Options defined here override system-wide defaults. The first matching Host block’s option value is used.
  3. System-wide config file (/etc/ssh/ssh_config): Provides default settings for all users on the system.

Enhancing Security: Disabling Password Authentication (Server-Side)

Once you rely on SSH keys, you can significantly improve your server’s security by disabling password-based logins entirely. This prevents brute-force password guessing attacks. This change is made on the remote server, not in your local ~/.ssh/config file.

  1. SSH into your remote server.
  2. Edit the SSH server configuration file (sshd_config): 
    sudo nano /etc/ssh/sshd_config
# or
sudo vim /etc/ssh/sshd_config
  3. Find and modify or add the following lines: 
    PasswordAuthentication no          # Disables plain password login
ChallengeResponseAuthentication no # Disables things like keyboard-interactive (often used for passwords/MFA)
# UsePAM no                        # Often set to 'no' if not using Pluggable Authentication Modules for SSH passwords.
                                   # Be cautious changing PAM settings if you don't understand them.
                                   # Setting the above two to 'no' usually suffices.
    Ensure PubkeyAuthentication yes is also set (it usually is by default).
  4. Save the file and exit.
  5. Restart the SSH service: 
    sudo systemctl restart sshd
# or on older systems:
# sudo systemctl restart ssh
# sudo service ssh restart

Critical: Before disabling password authentication, ensure your SSH key login is working correctly and you have copied your public key to the server for any user accounts you need to access! Otherwise, you might lock yourself out.

Conclusion

The SSH config file (~/.ssh/config) is an invaluable tool for anyone regularly working with remote servers. It simplifies connections, organizes settings, enhances security when paired with SSH keys, and ultimately saves you time and effort. Take a few minutes to set up aliases for your most-used hosts. Your future self will thank you! Don’t forget to consult man ssh_config to explore the wealth of options available.

(References: Using the SSH Config File - linuxize.com, How to Setup Passwordless SSH Login - linuxize.com)