ssh-remote

name	ssh-remote
category	system
description	Manage SSH connections, key management, remote command execution, tunneling, and file transfer with scp and rsync. Use when the user asks to connect to a remote server, generate SSH keys, set up port forwarding or tunnels, transfer files remotely, configure jump hosts, manage known_hosts, or set up SSH config for multiple hosts.
license	MIT
compatibility	Requires openssh-client (pre-installed on macOS and most Linux distributions)
metadata	{"author":"zeph","version":"1.0"}

SSH, SCP, and Rsync

Quick Reference

Task	Command
Connect	ssh user@host
Connect on port	ssh -p 2222 user@host
Run remote command	ssh user@host 'command'
Generate key	ssh-keygen -t ed25519
Copy key to server	ssh-copy-id user@host
Copy file to remote	scp file.txt user@host:/path/
Copy file from remote	scp user@host:/path/file.txt .
Sync directory	rsync -avz dir/ user@host:/path/
Local tunnel	ssh -L 8080:localhost:80 user@host

SSH Key Management

Generate Keys

# Ed25519 (recommended — fast, secure, short keys)
ssh-keygen -t ed25519 -C "user@hostname"

# Ed25519 with custom filename
ssh-keygen -t ed25519 -f ~/.ssh/id_project -C "user@hostname"

# RSA 4096-bit (for legacy systems that don't support Ed25519)
ssh-keygen -t rsa -b 4096 -C "user@hostname"

# Generate without passphrase (for automation only)
ssh-keygen -t ed25519 -f ~/.ssh/id_automation -N ""

# Change passphrase on existing key
ssh-keygen -p -f ~/.ssh/id_ed25519

# View key fingerprint
ssh-keygen -lf ~/.ssh/id_ed25519.pub

# View key in different format
ssh-keygen -lf ~/.ssh/id_ed25519.pub -E md5

Deploy Public Key

# Copy public key to remote server (recommended)
ssh-copy-id user@host

# Copy specific key
ssh-copy-id -i ~/.ssh/id_project.pub user@host

# Copy to non-standard port
ssh-copy-id -p 2222 user@host

# Manual method (when ssh-copy-id is unavailable)
cat ~/.ssh/id_ed25519.pub | ssh user@host 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

SSH Agent

# Start agent (if not running)
eval "$(ssh-agent -s)"

# Add key to agent
ssh-add ~/.ssh/id_ed25519

# Add key with timeout (auto-remove after 1 hour)
ssh-add -t 3600 ~/.ssh/id_ed25519

# List keys in agent
ssh-add -l

# Remove specific key
ssh-add -d ~/.ssh/id_ed25519

# Remove all keys
ssh-add -D

# macOS: add key to Keychain
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

SSH Connection

Basic Connection

# Connect as specific user
ssh user@host

# Connect on non-standard port
ssh -p 2222 user@host

# Connect with specific key
ssh -i ~/.ssh/id_project user@host

# Verbose output (debugging)
ssh -v user@host      # level 1
ssh -vv user@host     # level 2
ssh -vvv user@host    # level 3 (most verbose)

# Force password authentication
ssh -o PreferredAuthentications=password user@host

# Force key authentication
ssh -o PreferredAuthentications=publickey user@host

# Disable host key checking (lab/ephemeral hosts only)
ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null user@host

# Connect with X11 forwarding
ssh -X user@host

# Allocate pseudo-terminal (for interactive commands via script)
ssh -t user@host 'sudo systemctl restart nginx'

Remote Command Execution

# Run single command
ssh user@host 'uptime'

# Run command with arguments
ssh user@host 'df -h /home'

# Run multiple commands
ssh user@host 'cd /app && git pull && systemctl restart app'

# Run command with sudo
ssh -t user@host 'sudo systemctl status nginx'

# Run command with environment variable
ssh user@host 'LANG=C df -h'

# Pipe local data to remote command
cat data.csv | ssh user@host 'cat > /tmp/data.csv'

# Run local script on remote host
ssh user@host 'bash -s' < local_script.sh

# Run local script with arguments
ssh user@host 'bash -s' < local_script.sh -- arg1 arg2

# Capture remote output in local variable
result=$(ssh user@host 'cat /etc/hostname')

SSH Config (~/.ssh/config)

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

# Named host with short alias
Host myserver
    HostName 192.168.1.100
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_project

# Jump host (bastion) setup
Host bastion
    HostName bastion.example.com
    User jumpuser
    IdentityFile ~/.ssh/id_bastion

Host internal-*
    ProxyJump bastion
    User admin
    IdentityFile ~/.ssh/id_internal

Host internal-web
    HostName 10.0.1.10

Host internal-db
    HostName 10.0.1.20

# Wildcard host pattern
Host *.staging.example.com
    User deploy
    IdentityFile ~/.ssh/id_staging

# Tunnel configuration (persistent)
Host tunnel-db
    HostName db-server.example.com
    User admin
    LocalForward 5432 localhost:5432
    IdentityFile ~/.ssh/id_db

# Multiple jump hosts
Host deep-internal
    HostName 10.0.2.50
    ProxyJump bastion1,bastion2
    User admin

Usage after config:

# Connect using alias
ssh myserver

# Connect to internal host via bastion (automatic jump)
ssh internal-web

# Start DB tunnel
ssh -N tunnel-db   # then connect to localhost:5432

SSH Tunneling (Port Forwarding)

Local Port Forwarding (-L)

Access a remote service through a local port.

# Forward local 8080 to remote's localhost:80
ssh -L 8080:localhost:80 user@host

# Access remote database via local port
ssh -L 5432:localhost:5432 user@db-server

# Forward to a third host through SSH server
ssh -L 3306:db-host:3306 user@bastion

# Background tunnel (no shell)
ssh -fNL 8080:localhost:80 user@host

# Bind to all interfaces (not just localhost)
ssh -L 0.0.0.0:8080:localhost:80 user@host

# Multiple forwards
ssh -L 8080:localhost:80 -L 8443:localhost:443 user@host

Remote Port Forwarding (-R)

Make a local service accessible from the remote side.

# Expose local port 3000 on remote port 9000
ssh -R 9000:localhost:3000 user@host

# Background tunnel
ssh -fNR 9000:localhost:3000 user@host

# Bind to all interfaces on remote (requires GatewayPorts yes in sshd_config)
ssh -R 0.0.0.0:9000:localhost:3000 user@host

Dynamic Port Forwarding (-D) — SOCKS Proxy

# Create SOCKS5 proxy on local port 1080
ssh -D 1080 user@host

# Background SOCKS proxy
ssh -fND 1080 user@host

# Use with curl
curl --socks5 localhost:1080 https://example.com

# Use with any application that supports SOCKS5
export ALL_PROXY=socks5://localhost:1080

Jump Hosts (ProxyJump)

# Single jump host
ssh -J bastion user@internal-server

# Multiple jump hosts
ssh -J bastion1,bastion2 user@internal-server

# Jump with specific user and port
ssh -J jumpuser@bastion:2222 admin@internal

# SCP through jump host
scp -J bastion file.txt user@internal:/path/

# Rsync through jump host
rsync -avz -e "ssh -J bastion" dir/ user@internal:/path/

File Transfer — SCP

# Copy file to remote
scp file.txt user@host:/remote/path/

# Copy file from remote
scp user@host:/remote/file.txt /local/path/

# Copy directory recursively
scp -r dir/ user@host:/remote/path/

# Custom port
scp -P 2222 file.txt user@host:/path/

# Specific key
scp -i ~/.ssh/id_project file.txt user@host:/path/

# Preserve timestamps and permissions
scp -p file.txt user@host:/path/

# Bandwidth limit (KB/s)
scp -l 1000 large-file.tar.gz user@host:/path/

# Copy between two remote hosts
scp user1@host1:/path/file.txt user2@host2:/path/

# Multiple files
scp file1.txt file2.txt user@host:/path/

# Through jump host
scp -J bastion file.txt user@internal:/path/

File Transfer — Rsync

Rsync transfers only changed parts of files, making subsequent syncs much faster.

# Sync directory to remote (trailing / matters)
rsync -avz dir/ user@host:/remote/dir/

# Sync from remote to local
rsync -avz user@host:/remote/dir/ local-dir/

# Dry run (show what would change)
rsync -avzn dir/ user@host:/remote/dir/

# Delete files on destination that don't exist in source
rsync -avz --delete dir/ user@host:/remote/dir/

# Exclude patterns
rsync -avz --exclude='*.log' --exclude='node_modules' dir/ user@host:/path/

# Exclude from file
rsync -avz --exclude-from='rsync-exclude.txt' dir/ user@host:/path/

# Custom SSH port
rsync -avz -e "ssh -p 2222" dir/ user@host:/path/

# Custom SSH key
rsync -avz -e "ssh -i ~/.ssh/id_project" dir/ user@host:/path/

# Bandwidth limit (KB/s)
rsync -avz --bwlimit=1000 dir/ user@host:/path/

# Show progress
rsync -avz --progress dir/ user@host:/path/
rsync -avz --info=progress2 dir/ user@host:/path/   # overall progress

# Compress during transfer
rsync -avz dir/ user@host:/path/

# Preserve hard links
rsync -avzH dir/ user@host:/path/

# Resume interrupted transfer
rsync -avz --partial --append dir/ user@host:/path/

# Checksum-based comparison (instead of timestamp+size)
rsync -avzc dir/ user@host:/path/

Rsync Flags

Flag	Meaning
-a	Archive mode (recursive, preserves permissions, symlinks, timestamps, group, owner)
-v	Verbose
-z	Compress during transfer
-n	Dry run
-P	Show progress + keep partial files
-H	Preserve hard links
-e	Specify remote shell
--delete	Delete extraneous files on receiver
--exclude	Exclude pattern
--bwlimit	Bandwidth limit in KB/s

Known Hosts Management

# View known hosts
cat ~/.ssh/known_hosts

# Remove specific host entry
ssh-keygen -R hostname
ssh-keygen -R "[hostname]:port"
ssh-keygen -R 192.168.1.100

# Hash known hosts (privacy)
ssh-keygen -H -f ~/.ssh/known_hosts

# Scan and add host key manually
ssh-keyscan -t ed25519 hostname >> ~/.ssh/known_hosts
ssh-keyscan -p 2222 hostname >> ~/.ssh/known_hosts

Permissions Reference

SSH is strict about file permissions. Incorrect permissions cause silent authentication failures.

# Directory permissions
chmod 700 ~/.ssh

# Private key
chmod 600 ~/.ssh/id_ed25519

# Public key
chmod 644 ~/.ssh/id_ed25519.pub

# authorized_keys
chmod 600 ~/.ssh/authorized_keys

# config
chmod 600 ~/.ssh/config

# known_hosts
chmod 644 ~/.ssh/known_hosts

Important Notes

• Always prefer Ed25519 keys over RSA for new setups (shorter, faster, more secure)
• Use ssh-copy-id instead of manually editing authorized_keys
• Set IdentitiesOnly yes in SSH config to avoid sending all keys to every server
• Use ServerAliveInterval to prevent idle connections from being dropped by firewalls
• For tunnels, use -fN flags to run in background without a shell
• The trailing / in rsync source path matters: dir/ syncs contents, dir syncs the directory itself
• Use rsync --dry-run before --delete to verify what will be removed
• Never disable StrictHostKeyChecking on production or public networks
• Use ProxyJump (SSH 7.3+) instead of the older ProxyCommand for jump hosts
• SSH agent forwarding (-A) is convenient but carries security risks; prefer ProxyJump
• Keep ~/.ssh/config permissions at 600; SSH may silently ignore it otherwise