SSH Config Mastery: Organize Connections Like a Pro

The SSH config file (~/.ssh/config) is more powerful than most people realize. Beyond simple host aliases, it supports conditional logic, multi-hop connections, and per-host security policies.

Basic Structure

# ~/.ssh/config
Host hostname
    Option1 value1
    Option2 value2

Essential Patterns

Pattern 1: Simple Alias

Host prod
    HostName production.example.com
    User deploy
    IdentityFile ~/.ssh/prod_key

Usage: ssh prod instead of ssh deploy@production.example.com -i ~/.ssh/prod_key

Pattern 2: Wildcard Defaults

# Default for all hosts
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    AddKeysToAgent yes

# Override for specific hosts
Host *.example.com
    User admin
    IdentityFile ~/.ssh/work_key

Host *.personal.com
    User me
    IdentityFile ~/.ssh/personal_key

Pattern 3: ProxyJump (Multi-Hop)

# Bastion host
Host bastion
    HostName bastion.example.com
    User admin

# Internal server via bastion
Host internal
    HostName internal-server.local
    User deploy
    ProxyJump bastion

Usage: ssh internal automatically tunnels through bastion.

Pattern 4: Multiple Jump Hosts

Host region1-gateway
    HostName gw.region1.example.com

Host region1-server
    HostName server.region1.local
    ProxyJump region1-gateway

Host region2-gateway
    HostName gw.region2.example.com

Host region2-server
    HostName server.region2.local
    ProxyJump region2-gateway

Pattern 5: Port Forwarding

Host dev-server
    HostName dev.example.com
    User developer
    LocalForward 5432 localhost:5432
    LocalForward 6379 localhost:6379

Usage: ssh dev-server automatically forwards PostgreSQL and Redis.

Pattern 6: Dynamic Port Forwarding (SOCKS)

Host socks-proxy
    HostName proxy.example.com
    User admin
    DynamicForward 1080

Usage: ssh socks-proxy then configure browser to use SOCKS proxy at localhost:1080.

Advanced Features

Match Blocks

# Apply settings based on criteria
Match Host *.production.*
    LogLevel QUIET
    StrictHostKeyChecking yes

Match User root
    LogLevel VERBOSE

Match OriginalHost github.com
    IdentityFile ~/.ssh/github_key
    IdentitiesOnly yes

Conditional Authentication

Host secure-server
    HostName secure.example.com
    User admin
    # Try key first, then password
    PreferredAuthentications publickey,password
    PubkeyAuthentication yes
    PasswordAuthentication yes

Certificate-Based Auth

Host *.example.com
    CertificateFile ~/.ssh/id_ed25519-cert.pub
    IdentityFile ~/.ssh/id_ed25519

Per-Host Security Policies

# High security for production
Host *.prod.*
    StrictHostKeyChecking yes
    UpdateHostKeys no
    IdentityAgent none
    IdentitiesOnly yes

# Relaxed for development
Host *.dev.*
    StrictHostKeyChecking accept-new
    ForwardAgent yes

Real-World Examples

Example 1: Corporate Environment

# Corporate bastion
Host corp-bastion
    HostName bastion.corp.example.com
    User $USER
    IdentityFile ~/.ssh/corp_key
    CertificateFile ~/.ssh/corp_key-cert.pub

# Internal servers via bastion
Host *.internal.corp.example.com
    ProxyJump corp-bastion
    User $USER
    IdentityFile ~/.ssh/corp_key

# GitHub with corporate key
Host github.com
    IdentityFile ~/.ssh/github_corp_key
    IdentitiesOnly yes

Example 2: Multi-Cloud Setup

# AWS servers
Host *.aws.example.com
    User ec2-user
    IdentityFile ~/.ssh/aws_key
    ProxyJump aws-bastion

Host aws-bastion
    HostName bastion.aws.example.com
    User admin
    IdentityFile ~/.ssh/aws_key

# GCP servers
Host *.gcp.example.com
    User $USER
    IdentityFile ~/.ssh/gcp_key
    ProxyJump gcp-bastion

Host gcp-bastion
    HostName bastion.gcp.example.com
    User $USER
    IdentityFile ~/.ssh/gcp_key

# Azure servers
Host *.azure.example.com
    User azureuser
    IdentityFile ~/.ssh/azure_key

Example 3: Development Workflow

# Local development
Host localhost
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

# Docker containers
Host docker-*
    HostName localhost
    User root
    Port 2222
    StrictHostKeyChecking no

# Vagrant VMs
Host vagrant-*
    HostName localhost
    User vagrant
    Port 2200
    IdentityFile ~/.vagrant.d/insecure_private_key
    StrictHostKeyChecking no

Security Best Practices

1. Restrict Agent Forwarding

# Only forward to trusted hosts
Host trusted.example.com
    ForwardAgent yes

Host *
    ForwardAgent no

2. Enforce Key-Only Auth

Host *.production.*
    PreferredAuthentications publickey
    PasswordAuthentication no

3. Limit Key Exposure

Host github.com
    IdentityFile ~/.ssh/github_key
    IdentitiesOnly yes
    AddKeysToAgent no

4. Verify Host Keys

Host *
    StrictHostKeyChecking ask
    UpdateHostKeys yes

Debugging

Test Configuration

# Show resolved config for host
ssh -G hostname

# Verbose connection
ssh -vvv hostname

Common Issues

Problem: Wrong key used

# Fix: Specify IdentitiesOnly
Host hostname
    IdentityFile ~/.ssh/specific_key
    IdentitiesOnly yes

Problem: Connection timeout

# Fix: Add keepalive
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

Problem: Permission denied

# Fix: Check key permissions
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_*

FoxTerm SSH Config Integration

FoxTerm reads and respects your SSH config:

Config Import

• Automatically loads ~/.ssh/config
• Shows all defined hosts in sidebar
• Respects ProxyJump chains
• Uses specified identity files

Visual Editor

• Edit SSH config with syntax highlighting
• Validate configuration
• Test connections before saving
• Backup and restore

Enhanced Features

• Visual ProxyJump chain display
• Port forwarding status
• Certificate expiration warnings
• Key usage tracking

Conclusion

Mastering SSH config patterns transforms how you manage remote connections. From simple aliases to complex multi-hop setups, the config file provides declarative, reusable connection definitions.

FoxTerm integrates seamlessly with your SSH config, making complex setups visual and manageable.

---

FoxTerm Pro includes advanced SSH config management. Download at foxterm.app.