Mastering SSH Config on Ubuntu: Simplify Your Remote Connections

Stop typing ssh username@192.168.1.100 -p 2222 -i ~/.ssh/my_key.pem every single time you connect to a server.

With SSH config (~/.ssh/config), you can replace long, cumbersome SSH commands with clean shortcuts like ssh prod or ssh staging.

This guide walks you through setting up and optimizing your SSH configuration file on Ubuntu.

🛠️ Step 1: Create the SSH Config File

SSH is strict about permissions. If your configuration or .ssh folder has overly open permissions, SSH will ignore them for security reasons.

Run the following commands in your terminal:

# Ensure the .ssh directory exists with restricted permissions (700)
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Create the config file and set read/write permissions for user only (600)
touch ~/.ssh/config
chmod 600 ~/.ssh/config

Open the config file in your favorite text editor:

nano ~/.ssh/config

⚙️ Core Directives Explained

Before jumping into examples, here are the key directives you'll use:

🚀 Practical Examples

1. Basic Host Shortcut

Instead of typing ssh developer@192.168.1.50, set up an alias.

Host dev
    HostName 192.168.1.50
    User developer

Usage:

ssh dev

2. Custom Port & Specific Private Key

For servers running on custom ports (e.g., 2222) using a specific SSH key:

Host staging
    HostName staging.example.com
    User ubuntu
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_staging
    IdentitiesOnly yes

Usage:

ssh staging

3. Bastion / Jump Host (ProxyJump)

Connecting to an internal server (e.g., private database server 10.0.0.5) through a publicly exposed Bastion/Jump server:

# Public Bastion Host
Host bastion
    HostName bastion.example.com
    User admin
    IdentityFile ~/.ssh/id_rsa_bastion

# Private Internal Server
Host internal-db
    HostName 10.0.0.5
    User ubuntu
    IdentityFile ~/.ssh/id_rsa_internal
    ProxyJump bastion

Usage:

ssh internal-db

SSH will automatically route your connection through the bastion server!

4. Global Settings & Keep-Alive Pings

Prevent SSH connections from dropping or hanging due to idle timeouts by applying wildcard settings (Host *).

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    AddKeysToAgent yes

• ServerAliveInterval 60: Sends a keep-alive signal every 60 seconds.
• ServerAliveCountMax 3: Drops connection after 3 unacknowledged signals.
• AddKeysToAgent yes: Automatically adds keys to ssh-agent upon connection.

5. Connection Multiplexing (Blazing Fast Re-connections)

Multiplexing reuses an existing SSH connection for new terminal windows, scp, or rsync transfers, eliminating key exchange overhead.

First, create a socket directory:

mkdir -p ~/.ssh/sockets

Then add this block to your ~/.ssh/config:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h:%p
    ControlPersist 10m

💡 Bonus: Auto-Load SSH Keys into ssh-agent on Login

Add this snippet to the bottom of your ~/.bashrc (or ~/.zshrc) to ensure ssh-agent is running without starting multiple redundant instances:

# SSH Agent Auto-Start
SSH_ENV="$HOME/.ssh/agent-environment"

function start_agent {
    echo "Initializing new SSH agent..."
    /usr/bin/ssh-agent | sed 's/^echo/#echo/' > "${SSH_ENV}"
    chmod 600 "${SSH_ENV}"
    . "${SSH_ENV}" > /dev/null
    /usr/bin/ssh-add
}

if [ -f "${SSH_ENV}" ]; then
    . "${SSH_ENV}" > /dev/null
    ps -ef | grep ${SSH_AGENT_PID} | grep ssh-agent$ > /dev/null || {
        start_agent;
    }
else
    start_agent;
fi

Reload shell settings:

source ~/.bashrc

📌 Summary Checklist

• [ ] Folder permissions: chmod 700 ~/.ssh
• [ ] Config file permissions: chmod 600 ~/.ssh/config
• [ ] Specific hosts defined before wildcard (Host *) sections
• [ ] Tested shortcut with ssh <alias-name>

Happy Coding! 🚀