DEV Community

Cover image for Mastering SSH Config on Ubuntu: Simplify Your Remote Connections
Md Asaduzzaman
Md Asaduzzaman

Posted on

Mastering SSH Config on Ubuntu: Simplify Your Remote Connections

#devops #linux #shell #ubuntu

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
Enter fullscreen mode Exit fullscreen mode

Open the config file in your favorite text editor:

nano ~/.ssh/config
Enter fullscreen mode Exit fullscreen mode

⚙️ Core Directives Explained

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

Directive Description
Host The nickname/alias you use in terminal (e.g., ssh myserver).
HostName The real IP address or domain name of the remote server.
User The username on the remote server (e.g., root, ubuntu).
Port The SSH port on the remote server (default is 22).
IdentityFile Path to the specific private SSH key for this host.
IdentitiesOnly Forces SSH to use only specified key file, preventing access denied errors when holding multiple keys.

🚀 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
Enter fullscreen mode Exit fullscreen mode

Usage:

ssh dev
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Usage:

ssh staging
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Usage:

ssh internal-db
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

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

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

💡 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
Enter fullscreen mode Exit fullscreen mode

Reload shell settings:

source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

📌 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! 🚀

Top comments (0)