SSH Tunnel

SSH tunneling, port forwarding, and secure remote access. Covers local/remote/dynamic forwards, jump hosts, ProxyCommand, multiplexing, key management, and connection debugging.

When to Use

Accessing a remote database through a firewall (local port forward)
Exposing a local dev server to a remote machine (remote port forward)
Using a remote server as a SOCKS proxy (dynamic forward)
Connecting through bastion/jump hosts
Managing SSH keys and agent forwarding
Transferring files securely (scp, rsync)
Debugging SSH connection failures

Port Forwarding

Local forward (access remote service locally)

# Forward local port 5432 to remote's localhost:5432
# Use case: access a remote PostgreSQL database as if it were local
ssh -L 5432:localhost:5432 user@remote-server
Then connect locally:
psql -h localhost -p 5432 -U dbuser mydb
Forward to a different host accessible from the remote
Remote server can reach db.internal:5432, but you can't
ssh -L 5432:db.internal:5432 user@remote-server
Forward multiple ports
ssh -L 5432:db.internal:5432 -L 6379:redis.internal:6379 user@remote-server
Run in background (no shell)
ssh -fNL 5432:db.internal:5432 user@remote-server
-f = background after auth
-N = no remote command
-L = local forward

Remote forward (expose local service remotely)

# Make your local port 3000 accessible on the remote server's port 8080
ssh -R 8080:localhost:3000 user@remote-server
# On the remote: curl http://localhost:8080 → hits your local :3000
Expose to all interfaces on the remote (not just localhost)
Requires GatewayPorts yes in remote sshd_config
ssh -R 0.0.0.0:8080:localhost:3000 user@remote-server
Background mode

ssh -fNR 8080:localhost:3000 user@remote-server

Dynamic forward (SOCKS proxy)

# Create a SOCKS5 proxy on local port 1080
ssh -D 1080 user@remote-server
Route browser traffic through the tunnel
Configure browser proxy: SOCKS5, localhost:1080
Use with curl
curl --socks5-hostname localhost:1080 https://example.com
Background mode

ssh -fND 1080 user@remote-server

Jump Hosts / Bastion

ProxyJump (simplest, OpenSSH 7.3+)

# Connect through a bastion host
ssh -J bastion-user@bastion.example.com target-user@internal-server
Chain multiple jumps
ssh -J bastion1,bastion2 target-user@internal-server
With port forward through bastion

ssh -J bastion-user@bastion -L 5432:db.internal:5432 target-user@app-server

ProxyCommand (older systems, more flexible)

# Equivalent to ProxyJump but works on older OpenSSH
ssh -o ProxyCommand="ssh -W %h:%p bastion-user@bastion" target-user@internal-server

SSH Config for jump hosts

# ~/.ssh/config
Bastion host
Host bastion
HostName bastion.example.com
User bastion-user
IdentityFile ~/.ssh/bastion_key
Internal servers (automatically use bastion)
Host app-server
HostName 10.0.1.50
User deploy
ProxyJump bastion
Host db-server
HostName 10.0.2.30
User admin
ProxyJump bastion
LocalForward 5432 localhost:5432
Now just: ssh app-server
Or: ssh db-server (auto-forwards port 5432)

SSH Config Patterns

Essential config

# ~/.ssh/config
Global defaults
Host *
ServerAliveInterval 60
ServerAliveCountMax 3
AddKeysToAgent yes
IdentitiesOnly yes
Named hosts
Host prod
HostName 203.0.113.50
User deploy
IdentityFile ~/.ssh/prod_ed25519
Port 2222
Host staging
HostName staging.example.com
User deploy
IdentityFile ~/.ssh/staging_ed25519
Wildcard patterns

Host *.dev.example.com
User developer
IdentityFile ~/.ssh/dev_key
StrictHostKeyChecking no
UserKnownHostsFile /dev/null

Connection multiplexing (reuse connections)

# ~/.ssh/config
Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600
First connection opens socket, subsequent connections reuse it
Much faster for repeated ssh/scp/rsync to same host

# Create socket directory
mkdir -p ~/.ssh/sockets

# Manually manage control socket
ssh -O check prod       # Check if connection is alive
ssh -O stop prod        # Close the master connection
ssh -O exit prod        # Close immediately

Key Management

Generate keys

# Ed25519 (recommended — fast, secure, short keys)
ssh-keygen -t ed25519 -C "user@machine" -f ~/.ssh/mykey_ed25519
RSA 4096 (wider compatibility)
ssh-keygen -t rsa -b 4096 -C "user@machine" -f ~/.ssh/mykey_rsa
Generate without passphrase (for automation only)
ssh-keygen -t ed25519 -N "" -f ~/.ssh/deploy_key

Deploy keys

# Copy public key to remote server
ssh-copy-id -i ~/.ssh/mykey_ed25519.pub user@remote-server
Manual (if ssh-copy-id unavailable)
cat ~/.ssh/mykey_ed25519.pub | ssh user@remote-server "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

SSH Agent

# Start agent (usually auto-started)
eval "$(ssh-agent -s)"
Add key to agent
ssh-add ~/.ssh/mykey_ed25519
Add with expiry (key removed after timeout)
ssh-add -t 3600 ~/.ssh/mykey_ed25519
List loaded keys
ssh-add -l
Remove all keys
ssh-add -D
Agent forwarding (use your local keys on remote hosts)
ssh -A user@remote-server
On remote: ssh git@github.com  → uses your local key
SECURITY: only forward to trusted hosts

File permissions

# SSH is strict about permissions. Fix common issues:
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519          # Private key
chmod 644 ~/.ssh/id_ed25519.pub      # Public key
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/authorized_keys

File Transfer

scp

# Copy file to remote
scp file.txt user@remote:/path/to/destination/
Copy from remote
scp user@remote:/path/to/file.txt ./local/
Copy directory recursively
scp -r ./local-dir user@remote:/path/to/
Through jump host
scp -o ProxyJump=bastion file.txt user@internal:/path/
With specific key and port

scp -i ~/.ssh/mykey -P 2222 file.txt user@remote:/path/

rsync over SSH

# Sync directory (only changed files)
rsync -avz ./local-dir/ user@remote:/path/to/remote-dir/
Dry run (preview changes)
rsync -avzn ./local-dir/ user@remote:/path/to/remote-dir/
Delete files on remote that don't exist locally
rsync -avz --delete ./local-dir/ user@remote:/path/to/remote-dir/
Exclude patterns
rsync -avz --exclude='node_modules' --exclude='.git' ./project/ user@remote:/deploy/
With specific SSH options
rsync -avz -e "ssh -i ~/.ssh/deploy_key -p 2222" ./dist/ user@remote:/var/www/
Resume interrupted transfer
rsync -avz --partial --progress large-file.tar.gz user@remote:/path/
Through jump host

rsync -avz -e "ssh -J bastion" ./files/ user@internal:/path/

Connection Debugging

Verbose output

# Increasing verbosity levels
ssh -v user@remote       # Basic debug
ssh -vv user@remote      # More detail
ssh -vvv user@remote     # Maximum detail
Common issues visible in verbose output:
"Connection refused" → SSH server not running or wrong port
"Connection timed out" → Firewall blocking, wrong IP
"Permission denied (publickey)" → Key not accepted
"Host key verification failed" → Server fingerprint changed

Test connectivity

# Check if SSH port is open
nc -zv remote-host 22
# or
ssh -o ConnectTimeout=5 -o BatchMode=yes user@remote echo ok
Check which key the server accepts
ssh -o PreferredAuthentications=publickey -v user@remote 2>&1 | grep "Offering|Accepted"
Test config without connecting

ssh -G remote-host   # Print effective config for this host

Common fixes

# "WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED"
# Server was reinstalled / IP reassigned
ssh-keygen -R remote-host   # Remove old fingerprint
ssh user@remote-host        # Accept new fingerprint
"Too many authentication failures"
SSH agent is offering too many keys
ssh -o IdentitiesOnly=yes -i ~/.ssh/specific_key user@remote
"Connection closed by remote host"
Often: MaxSessions or MaxStartups limit on server
Or: fail2ban banned your IP
Tunnel keeps dying
Add keepalive in config or command line:
ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5 user@remote
Permission denied despite correct key
Check remote: /var/log/auth.log or /var/log/secure
Common: wrong permissions on ~/.ssh or authorized_keys

Kill stuck SSH sessions

# If SSH session hangs (frozen terminal):
# Type these characters in sequence:
~.          # Disconnect
~?          # Show escape commands
~#          # List forwarded connections
~&          # Background SSH (when waiting for tunnel to close)
# The ~ must be the first character on a new line (press Enter first)

Tips

Use
```
~/.ssh/config
```
for everything. Named hosts with stored settings are faster and less error-prone than typing long commands.
Ed25519 keys are preferred over RSA. They're shorter, faster, and equally secure.
Connection multiplexing (
```
ControlMaster
```
) makes repeated connections instant. Enable it globally.
```
rsync
```
is almost always better than
```
scp
```
for anything beyond a single file. It handles interruptions, only transfers changes, and supports compression.
Agent forwarding (
```
-A
```
) is convenient but a security risk on untrusted servers. The remote host can use your agent to authenticate as you. Prefer
```
ProxyJump
```
instead.
```
ServerAliveInterval 60
```
in config prevents most "broken pipe" disconnections.
Keep your
```
~/.ssh/config
```
organized with comments. Future-you will appreciate it.
The
```
~.
```
escape sequence is the only way to kill a stuck SSH session without closing the terminal.

SSH Tunnel

AI Skill Market Insights

Be Part of the 0+ Developer Community

SSH Tunnel

When to Use

Port Forwarding

Local forward (access remote service locally)

Then connect locally:

Forward to a different host accessible from the remote

Remote server can reach db.internal:5432, but you can't

Forward multiple ports

Run in background (no shell)

-f = background after auth

-N = no remote command

-L = local forward

Remote forward (expose local service remotely)

Expose to all interfaces on the remote (not just localhost)

Requires GatewayPorts yes in remote sshd_config

Background mode

Dynamic forward (SOCKS proxy)

Route browser traffic through the tunnel

Configure browser proxy: SOCKS5, localhost:1080

Use with curl

Background mode

Jump Hosts / Bastion

ProxyJump (simplest, OpenSSH 7.3+)

Chain multiple jumps

With port forward through bastion

ProxyCommand (older systems, more flexible)

SSH Config for jump hosts

Bastion host

Internal servers (automatically use bastion)

Now just: ssh app-server

Or: ssh db-server (auto-forwards port 5432)

SSH Config Patterns

Essential config

Global defaults

Named hosts

Wildcard patterns

Connection multiplexing (reuse connections)

First connection opens socket, subsequent connections reuse it

Much faster for repeated ssh/scp/rsync to same host

Key Management

Generate keys

RSA 4096 (wider compatibility)

Generate without passphrase (for automation only)

Deploy keys

Manual (if ssh-copy-id unavailable)

SSH Agent

Add key to agent

Add with expiry (key removed after timeout)

List loaded keys

Remove all keys

Agent forwarding (use your local keys on remote hosts)

On remote: ssh git@github.com → uses your local key

SECURITY: only forward to trusted hosts

File permissions

File Transfer

scp

Copy from remote

Copy directory recursively

Through jump host

With specific key and port

rsync over SSH

Dry run (preview changes)

Delete files on remote that don't exist locally

Exclude patterns

With specific SSH options

Resume interrupted transfer

Through jump host

Connection Debugging

Verbose output

Common issues visible in verbose output:

"Connection refused" → SSH server not running or wrong port

"Connection timed out" → Firewall blocking, wrong IP

"Permission denied (publickey)" → Key not accepted

"Host key verification failed" → Server fingerprint changed

Test connectivity

Check which key the server accepts

Test config without connecting