autossh-tunnel-dockerized

SSH Config Configuration Guide

中文版 English

This guide explains how to configure the SSH config file (~/.ssh/config) for use with the autossh-tunnel-dockerized project. The SSH config file is essential for defining connection parameters and ensuring smooth tunnel establishment.

Table of Contents

Overview

The SSH config file (~/.ssh/config) allows you to define connection parameters for SSH hosts, including:

This project relies heavily on the SSH config file because:

  1. Host Identification: The remote_host parameter in config.yaml references entries in your SSH config
  2. Authentication: SSH config specifies which private keys to use for each host
  3. Connection Parameters: Timeouts, ports, and other connection settings are defined here
  4. Simplified Configuration: Instead of specifying full connection details in each tunnel, you can use simple host aliases

SSH Config File Location

The SSH config file should be located at:

~/.ssh/config

If this file doesn’t exist, create it:

touch ~/.ssh/config
chmod 600 ~/.ssh/config

Basic Configuration

Simple Host Configuration

Host myserver
    HostName example.com
    User myuser
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Multiple Hosts

Host server1
    HostName 192.168.1.100
    User admin
    Port 22
    IdentityFile ~/.ssh/id_rsa

Host server2
    HostName server2.example.com
    User root
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Host jumphost
    HostName jump.example.com
    User jumpuser
    Port 22
    IdentityFile ~/.ssh/jump_key

Advanced Configuration

Connection Optimization

Host *
    # Enable connection multiplexing
    ControlMaster auto
    ControlPath ~/.ssh/sockets/ssh_mux_%h_%p_%r
    ControlPersist 600
    
    # Connection timeouts
    ServerAliveInterval 60
    ServerAliveCountMax 3
    ConnectTimeout 10
    
    # Security settings
    StrictHostKeyChecking yes
    UserKnownHostsFile ~/.ssh/known_hosts

Host production-server
    HostName prod.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/production_key
    
    # Specific settings for this host
    ServerAliveInterval 30
    TCPKeepAlive yes
    Compression yes

Jump Host Configuration

Host jumphost
    HostName jump.example.com
    User jumpuser
    Port 22
    IdentityFile ~/.ssh/jump_key

Host internal-server
    HostName 10.0.1.100
    User admin
    Port 22
    IdentityFile ~/.ssh/internal_key
    ProxyJump jumphost
    
    # Alternative syntax for older SSH versions
    # ProxyCommand ssh -W %h:%p jumphost

Wildcard Patterns

Host *.internal
    User admin
    Port 22
    IdentityFile ~/.ssh/internal_key
    ProxyJump jumphost

Host dev-*
    User developer
    Port 2222
    IdentityFile ~/.ssh/dev_key
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

Common Configuration Examples

Example 1: Simple VPS Configuration

Host vps1
    HostName 203.0.113.10
    User root
    Port 22
    IdentityFile ~/.ssh/vps1_key
    ServerAliveInterval 60
    ServerAliveCountMax 3

Corresponding config.yaml entry:

tunnels:
  - remote_host: "vps1"
    remote_port: 8080
    local_port: 3000
    direction: local_to_remote

Example 2: Corporate Environment with Jump Host

Host corporate-jump
    HostName jump.company.com
    User myusername
    Port 22
    IdentityFile ~/.ssh/company_key

Host internal-db
    HostName db.internal.company.com
    User dbuser
    Port 22
    IdentityFile ~/.ssh/db_key
    ProxyJump corporate-jump

Corresponding config.yaml entry:

tunnels:
  - remote_host: "internal-db"
    remote_port: 5432
    local_port: 5432
    direction: remote_to_local

Example 3: Multiple Environments

Host dev-server
    HostName dev.example.com
    User developer
    Port 2222
    IdentityFile ~/.ssh/dev_key

Host staging-server
    HostName staging.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/staging_key

Host prod-server
    HostName prod.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/prod_key
    StrictHostKeyChecking yes

Security Best Practices

1. File Permissions

Ensure proper permissions for SSH files:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub
chmod 600 ~/.ssh/known_hosts

2. Key Management

Host *
    # Only use keys specified in config
    IdentitiesOnly yes
    
    # Disable password authentication
    PasswordAuthentication no
    PubkeyAuthentication yes
    
    # Use strong ciphers
    Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr

3. Host Verification

Host trusted-servers
    HostName *.trusted.com
    StrictHostKeyChecking yes
    UserKnownHostsFile ~/.ssh/known_hosts

Host dev-*
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    LogLevel QUIET

Troubleshooting

Common Issues

  1. Permission Denied

    chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/private_key

  2. Host Key Verification Failed

    ssh-keyscan -H hostname >> ~/.ssh/known_hosts

  3. Connection Timeout

    Host slow-server
    ConnectTimeout 30
    ServerAliveInterval 60
    ServerAliveCountMax 10

Testing SSH Configuration

Test your SSH config before using with autossh:

# Test connection
ssh -T hostname

# Test with verbose output
ssh -v hostname

# Test specific config file
ssh -F ~/.ssh/config hostname

Debug Mode

Enable debug mode in your SSH config:

Host debug-server
    HostName example.com
    User myuser
    LogLevel DEBUG3
    IdentityFile ~/.ssh/debug_key

Integration with Autossh Tunnel

When using this SSH config with the autossh-tunnel project:

  1. Host References: Use the Host names from your SSH config as remote_host values in config.yaml
  2. Authentication: Ensure IdentityFile paths are correct and accessible from within the Docker container
  3. Permissions: The ~/.ssh directory is mounted as read-only in the container
  4. Testing: Always test SSH connections manually before configuring tunnels

Example Integration

SSH Config (~/.ssh/config):

Host tunnel-server
    HostName tunnel.example.com
    User tunneluser
    Port 22
    IdentityFile ~/.ssh/tunnel_key
    ServerAliveInterval 60
    ServerAliveCountMax 3

Tunnel Config (config/config.yaml):

tunnels:
  - remote_host: "tunnel-server"
    remote_port: 8080
    local_port: 3000
    direction: local_to_remote

For more information about the autossh-tunnel project, see the main README.

This site is open source. Improve this page.