DEV Community

Cover image for SSH Config File Mastery: Turning `~/.ssh/config` Into a Productivity Tool
Mahafuzur Rahaman
Mahafuzur Rahaman

Posted on

SSH Config File Mastery: Turning `~/.ssh/config` Into a Productivity Tool

#ai #ssh #cli #programming

Stop typing the same long SSH commands every day. One file eliminates the repetition and unlocks features most developers don't know exist.

Here's a test. How do you SSH into your staging server?

If the answer involves typing an IP address, a username, a port number, and a key file path every single time — this article is for you.

The ~/.ssh/config file lets you replace all of that with a single word. But it goes much further than aliases. With the right config, SSH becomes smarter: it automatically selects the right key, routes connections through jump hosts, keeps connections alive, compresses traffic, and handles dozens of edge cases without you thinking about them.

This is a complete guide to the SSH client config file — from the basics to patterns used by senior engineers and DevOps teams.

The Basics: What the Config File Is

~/.ssh/config is a plain text file that configures the behavior of the SSH client. Every time you run ssh, scp, sftp, or rsync over SSH, OpenSSH reads this file and applies the matching configuration.

If the file doesn't exist yet, create it:

mkdir -p ~/.ssh
touch ~/.ssh/config
chmod 600 ~/.ssh/config   # Important: must not be world-readable
Enter fullscreen mode Exit fullscreen mode

The file follows a simple structure:

Host <pattern>
    <Directive> <value>
    <Directive> <value>

Host <pattern>
    <Directive> <value>
Enter fullscreen mode Exit fullscreen mode

Each Host block applies to connections whose target matches the pattern. Patterns support wildcards. A Host * block applies to all connections.

Order matters: SSH reads the file top to bottom and applies the first matching value for each directive. Put specific host blocks before general wildcard blocks.

Part 1: The Essentials — Stop Typing Long Commands

Basic Host Alias

Before:

ssh -i ~/.ssh/id_ed25519_work -p 2222 ubuntu@203.0.113.50
Enter fullscreen mode Exit fullscreen mode

After, with config:

Host staging
    HostName 203.0.113.50
    User ubuntu
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes
Enter fullscreen mode Exit fullscreen mode

Now:

ssh staging
Enter fullscreen mode Exit fullscreen mode

This also works with scp, rsync, and any other SSH-based tool:

scp staging:/var/log/app.log ./
rsync -avz staging:/var/www/html/ ./backup/
Enter fullscreen mode Exit fullscreen mode

Common Directives Reference 

Host           Pattern to match against the target name
HostName       Actual hostname or IP to connect to
User           Remote username
Port           Remote port (default: 22)
IdentityFile   Path to private key
IdentitiesOnly Only use the specified key, not the agent
Compression    Enable data compression (yes/no)
ServerAliveInterval  Keepalive ping interval (seconds)
ServerAliveCountMax  Reconnect attempts before giving up
ConnectTimeout       Timeout for initial connection (seconds)
Enter fullscreen mode Exit fullscreen mode

Part 2: Wildcards and Pattern Matching

Config patterns aren't just for exact hostnames. They support glob-style wildcards.

* Matches Anything 

Host *.prod.example.com
    User ec2-user
    IdentityFile ~/.ssh/id_ed25519_prod
    ServerAliveInterval 60
Enter fullscreen mode Exit fullscreen mode

This applies to web.prod.example.com, db.prod.example.com, bastion.prod.example.com — any host in that subdomain.

? Matches a Single Character 

Host web-?
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_dev
Enter fullscreen mode Exit fullscreen mode

Matches web-1, web-2, web-a — but not web-10 or web-prod.

Multiple Patterns on One Host 

Host web db cache
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_work
Enter fullscreen mode Exit fullscreen mode

This block matches if the target is web, db, or cache. Useful for hosts that share configuration but are addressed by different names.

Negation With ! 

Host * !bastion.prod.example.com
    ServerAliveInterval 30
Enter fullscreen mode Exit fullscreen mode

Applies to all hosts except bastion.prod.example.com.

Part 3: Jump Hosts and ProxyJump

This is where the config file starts to feel like magic.

The Problem

Your production servers aren't publicly accessible. You connect through a bastion host:

# Old way: two-step connection
ssh ubuntu@bastion.example.com
# (now on bastion)
ssh ubuntu@db.internal
Enter fullscreen mode Exit fullscreen mode

This is clunky, leaves you with a shell on the bastion, and doesn't work with scp directly.

ProxyJump: The Clean Solution 

Host db.internal
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_prod
    ProxyJump bastion.example.com

Host bastion.example.com
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_prod
Enter fullscreen mode Exit fullscreen mode

Now ssh db.internal automatically routes through the bastion. Transparent to you, invisible in usage.

Wildcard ProxyJump for an Entire Private Network 

Host *.internal
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_prod
    ProxyJump bastion.example.com
Enter fullscreen mode Exit fullscreen mode

Any *.internal host goes through the bastion automatically. You never have to think about it.

Multi-Hop: Chaining Jump Hosts 

Host deep.internal
    ProxyJump bastion.example.com,internal-gateway.example.com
Enter fullscreen mode Exit fullscreen mode

Comma-separated jump hosts are traversed in order. SSH creates the full chain automatically.

ProxyJump vs. ProxyCommand

You may see older configs using ProxyCommand:

# Old way (still works, but verbose)
Host *.internal
    ProxyCommand ssh -W %h:%p bastion.example.com
Enter fullscreen mode Exit fullscreen mode

ProxyJump is cleaner and equivalent. Use ProxyJump for new configs.

Part 4: Identity Management — Right Key, Every Time

Managing multiple SSH keys is one of the most common sources of friction. The config file eliminates it.

Per-Client-Context Keys 

# Work infrastructure
Host *.work.example.com
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes

# Client A
Host *.clienta.com
    User deploy
    IdentityFile ~/.ssh/id_ed25519_clienta
    IdentitiesOnly yes

# Personal/GitHub
Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
    IdentitiesOnly yes
Enter fullscreen mode Exit fullscreen mode

IdentitiesOnly yes is important. Without it, SSH tries every key in your agent until one works or you hit MaxAuthTries. With it, only the specified key is tried. This prevents authentication failures on servers with low MaxAuthTries settings.

Multiple GitHub/GitLab Accounts

A classic pain point: work and personal GitHub accounts on the same machine.

Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
    IdentitiesOnly yes

Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes
Enter fullscreen mode Exit fullscreen mode

In your personal repo's git remote, use github-personal instead of github.com:

git remote set-url origin git@github-personal:yourusername/repo.git
Enter fullscreen mode Exit fullscreen mode

In work repos:

git remote set-url origin git@github-work:workorg/repo.git
Enter fullscreen mode Exit fullscreen mode

Each repo automatically uses the right key.

Part 5: Connection Persistence and Performance

ControlMaster: Reuse Existing Connections

By default, every ssh invocation opens a new TCP connection and runs the full handshake. With ControlMaster, subsequent connections to the same host reuse an existing socket.

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

Create the socket directory:

mkdir -p ~/.ssh/sockets
Enter fullscreen mode Exit fullscreen mode

Effect: your second ssh staging connects in milliseconds. Your rsync, scp, and ansible runs share the same connection pool. The master connection persists for 4 hours after the last session closes.

This is a significant productivity boost if you frequently open multiple connections to the same hosts.

Keepalive: Stop Connections From Dropping

Idle SSH connections drop when firewalls, NAT, or cloud load balancers close inactive sessions.

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
Enter fullscreen mode Exit fullscreen mode

SSH sends a keepalive packet every 60 seconds. If 3 consecutive packets go unanswered, the connection is considered dead. This keeps sessions alive through idle periods and gives clean failure detection.

Compression: Faster on Slow Links 

Host remote-dev
    Compression yes
Enter fullscreen mode Exit fullscreen mode

Compression reduces data volume at the cost of CPU. Valuable on slow or high-latency links (cellular, satellite, congested VPN). Generally not worth enabling on fast local/cloud networks.

ConnectTimeout: Fail Fast 

Host *
    ConnectTimeout 10
Enter fullscreen mode Exit fullscreen mode

Don't wait the default 2 minutes for a connection to a dead host. Fail in 10 seconds and move on.

Part 6: Environment and Forwarding Options

Agent Forwarding — With Caution

Agent forwarding allows the SSH agent on your local machine to be used on the remote server. This lets you SSH from the remote server to a third server using your local key — without copying private keys to the remote.

Host bastion.example.com
    ForwardAgent yes
Enter fullscreen mode Exit fullscreen mode

Use this carefully. When agent forwarding is enabled, anyone with root on the remote server can use your agent (and thus your keys) for the duration of your connection. Only enable it for hosts you fully trust.

A safer alternative for multi-hop access is ProxyJump, which doesn't expose your agent.

# Prefer this:
Host db.internal
    ProxyJump bastion.example.com

# Over this (when agent forwarding is only needed to reach the next hop):
Host bastion.example.com
    ForwardAgent yes
Enter fullscreen mode Exit fullscreen mode

X11 Forwarding

For running GUI applications over SSH:

Host dev-gui
    ForwardX11 yes
    ForwardX11Trusted no
Enter fullscreen mode Exit fullscreen mode

ForwardX11Trusted no is safer — it limits what the remote application can do with your X display. Use yes only if you need it.

Environment Variables

Pass local environment variables to the remote session:

Host dev
    SendEnv LANG LC_* EDITOR
Enter fullscreen mode Exit fullscreen mode

The server must have AcceptEnv configured to accept these variables in sshd_config.

Part 7: Real-World Config Patterns

The Team Bastion Setup 

# Bastion — the entry point to production
Host bastion
    HostName bastion.prod.example.com
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_prod
    IdentitiesOnly yes
    ServerAliveInterval 60
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h:%p
    ControlPersist 2h

# All internal prod hosts through bastion
Host *.prod.internal
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_prod
    IdentitiesOnly yes
    ProxyJump bastion

# Dev servers — more relaxed settings
Host *.dev.example.com
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519_dev
    IdentitiesOnly yes
    ServerAliveInterval 30
    StrictHostKeyChecking accept-new
Enter fullscreen mode Exit fullscreen mode

The Developer Workstation 

# GitHub — personal
Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes

# Work GitLab
Host gitlab.work.example.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes

# Local VMs
Host homelab
    HostName 192.168.1.100
    User ubuntu
    StrictHostKeyChecking accept-new
    UserKnownHostsFile ~/.ssh/known_hosts_local

# Default settings for everything
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    ConnectTimeout 10
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h:%p
    ControlPersist 1h
    HashKnownHosts yes
    IdentitiesOnly yes
Enter fullscreen mode Exit fullscreen mode

The CI/CD Pipeline Config

CI environments often need SSH config too. Write it dynamically during pipeline setup:

mkdir -p ~/.ssh && chmod 700 ~/.ssh

cat >> ~/.ssh/config << EOF
Host deploy-target
    HostName $DEPLOY_HOST
    User deploy
    IdentityFile ~/.ssh/deploy_key
    IdentitiesOnly yes
    StrictHostKeyChecking accept-new
    ConnectTimeout 15
EOF

chmod 600 ~/.ssh/config
echo "$DEPLOY_PRIVATE_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
Enter fullscreen mode Exit fullscreen mode

Part 8: Debugging Config Issues

Test What Config Will Be Applied 

ssh -G staging
Enter fullscreen mode Exit fullscreen mode

-G prints the full resolved configuration for staging without connecting. Shows exactly which options are active, where they came from, and what key will be used.

Verbose Mode 

ssh -v staging    # Basic debug
ssh -vv staging   # More verbose
ssh -vvv staging  # Maximum verbosity
Enter fullscreen mode Exit fullscreen mode

Look for lines like:

debug1: Reading configuration data /home/user/.ssh/config
debug1: /home/user/.ssh/config line 5: Applying options for staging
debug1: Trying private key: /home/user/.ssh/id_ed25519_work
Enter fullscreen mode Exit fullscreen mode

This tells you exactly which config block matched and which key is being tried.

Check File Permissions

SSH is strict about config file permissions. If permissions are wrong, SSH ignores the file:

chmod 600 ~/.ssh/config
chmod 700 ~/.ssh/
chmod 600 ~/.ssh/id_*          # Private keys
chmod 644 ~/.ssh/id_*.pub      # Public keys
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/known_hosts
Enter fullscreen mode Exit fullscreen mode

Common Issues

Symptom Likely Cause Fix
Config ignored entirely Wrong file permissions chmod 600 ~/.ssh/config
Wrong key being used Missing IdentitiesOnly yes Add to host block
ProxyJump failing Bastion block misconfigured Test bastion connection first
ControlMaster errors Socket directory missing mkdir -p ~/.ssh/sockets
Options not applying Wrong host pattern Run ssh -G hostname to debug

The Config File as Living Documentation

One underappreciated use of ~/.ssh/config: it's documentation.

A well-structured config file tells the story of your infrastructure. Which hosts exist. How they're accessed. Which environments use which keys. What's behind a bastion.

Keep it in version control (your dotfiles repo, your team's infrastructure repo). Comment it. Update it when infrastructure changes. It's a low-overhead way to maintain institutional knowledge about how your systems are connected.

# Production infrastructure
# Bastion: bastion.prod.example.com
# Last updated: 2024-01
# Key rotation: annually (next: 2025-01)

Host bastion
    ...
Enter fullscreen mode Exit fullscreen mode

Quick Reference: Most Useful Directives 

Host                    Pattern matching target hostname
HostName                Actual address to connect to
User                    Remote username
Port                    Remote port
IdentityFile            Path to private key
IdentitiesOnly          Only try specified keys (yes/no)
ProxyJump               Jump host(s), comma-separated
ForwardAgent            Forward local SSH agent (yes/no)
ServerAliveInterval     Keepalive interval in seconds
ServerAliveCountMax     Keepalive failure threshold
ControlMaster           Connection sharing (auto/yes/no)
ControlPath             Socket path for shared connections
ControlPersist          How long to keep master alive
Compression             Enable compression (yes/no)
ConnectTimeout          Initial connection timeout (seconds)
StrictHostKeyChecking   Host key policy (yes/accept-new/no)
HashKnownHosts          Hash known_hosts entries (yes/no)
LogLevel                Verbosity (QUIET/INFO/VERBOSE/DEBUG)
Enter fullscreen mode Exit fullscreen mode

The Bottom Line

The SSH config file is one of those tools that pays compounding dividends. You invest 30 minutes setting it up properly, and every SSH-related task for the rest of your career gets a little faster, a little less error-prone, and a little more automatic.

Start with your most-used hosts. Add Host * defaults for keepalives and connection sharing. Wire up your jump hosts. Handle your multiple GitHub accounts. In an hour, you'll have a config that feels like it was built for exactly your workflow — because it was.

# The one command to start:
ssh -G any-host-you-connect-to
# See what's currently configured, then improve from there.
Enter fullscreen mode Exit fullscreen mode

Follow for more practical SSH, infrastructure, and developer productivity content.

Top comments (0)