ssh-essentials

name	ssh-essentials
description	Essential SSH commands for secure remote access, key management, tunneling, and file transfers. Use when the user needs help with SSH connections, key generation, port forwarding, file transfers (scp/sftp/rsync), or SSH configuration. NOT for: general networking questions, VPN setup, or when SSH is not involved.

SSH Essentials

Secure Shell (SSH) for remote access and secure file transfers.

Basic Connection

Connecting

# Connect with username
ssh user@hostname

# Connect to specific port
ssh user@hostname -p 2222

# Connect with verbose output
ssh -v user@hostname

# Connect with specific key
ssh -i ~/.ssh/id_rsa user@hostname

# Connect and run command
ssh user@hostname 'ls -la'
ssh user@hostname 'uptime && df -h'

Interactive use

# Connect with forwarding agent
ssh -A user@hostname

# Connect with X11 forwarding (GUI apps)
ssh -X user@hostname
ssh -Y user@hostname  # Trusted X11

# Escape sequences (during session)
# ~. - Disconnect
# ~^Z - Suspend SSH
# ~# - List forwarded connections
# ~? - Help

SSH Keys

Generating keys

# Generate RSA key
ssh-keygen -t rsa -b 4096 -C "[e-mail]"

# Generate ED25519 key (recommended)
ssh-keygen -t ed25519 -C "[e-mail]"

# Generate with custom filename
ssh-keygen -t ed25519 -f ~/.ssh/id_myserver

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

Managing keys

# Copy public key to server
ssh-copy-id user@hostname

# Copy specific key
ssh-copy-id -i ~/.ssh/id_rsa.pub user@hostname

# Manual key copy
cat ~/.ssh/id_rsa.pub | ssh user@hostname 'cat >> ~/.ssh/authorized_keys'

Check key fingerprint

ssh-keygen -lf ~/.ssh/id_rsa.pub

Change key passphrase

ssh-keygen -p -f ~/.ssh/id_rsa

### SSH agent
```bash
# Start ssh-agent
eval $(ssh-agent)

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

# List keys in agent
ssh-add -l

# Remove key from agent
ssh-add -d ~/.ssh/id_rsa

# Remove all keys
ssh-add -D

# Set key lifetime (seconds)
ssh-add -t 3600 ~/.ssh/id_rsa

Windows 用户：Claude Code 自带 bash，以上命令直接可用。如果用原生 PowerShell，需先启用 ssh-agent 服务：Get-Service ssh-agent | Set-Service -StartupType Automatic

Port Forwarding & Tunneling

Local port forwarding

# Forward local port to remote
ssh -L 8080:localhost:80 user@hostname

# Forward to different remote host
ssh -L 8080:database.example.com:5432 user@jumphost

# Multiple forwards
ssh -L 8080:localhost:80 -L 3306:localhost:3306 user@hostname

Remote port forwarding

# Forward remote port to local
ssh -R 8080:localhost:3000 user@hostname

# Make service accessible from remote
ssh -R 9000:localhost:9000 user@publicserver

Dynamic port forwarding (SOCKS proxy)

# Create SOCKS proxy
ssh -D 1080 user@hostname
# Configure SOCKS5 proxy: localhost:1080

Background tunnels

# Run in background
ssh -f -N -L 8080:localhost:80 user@hostname

# Keep alive
ssh -o ServerAliveInterval=60 -L 8080:localhost:80 user@hostname

Configuration

SSH config file (~/.ssh/config)

# Simple host alias
Host myserver
    HostName 192.168.1.100
    User admin
    Port 2222

# With key and options
Host production
    HostName prod.example.com
    User deploy
    IdentityFile ~/.ssh/id_prod
    ForwardAgent yes

# Jump host (bastion)
Host internal
    HostName 10.0.0.5
    User admin
    ProxyJump bastion

Host bastion
    HostName bastion.example.com
    User admin

# Wildcard configuration
Host *.example.com
    User admin
    ForwardAgent yes

# Keep connections alive
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

Using config

# Connect using alias
ssh myserver

# Jump through bastion automatically
ssh internal

File Transfers

SCP (Secure Copy)

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

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

# Copy directory recursively
scp -r /local/dir user@hostname:/remote/dir/

# Copy with specific port
scp -P 2222 file.txt user@hostname:/path/

SFTP (Secure FTP)

# Connect to SFTP server
sftp user@hostname

# Common SFTP commands:
# pwd, lpwd, ls, lls, cd, lcd, get, put, mkdir, rm, exit

Rsync over SSH

# Sync directory
rsync -avz /local/dir/ user@hostname:/remote/dir/

# Sync with progress
rsync -avz --progress /local/dir/ user@hostname:/remote/dir/

# Sync with delete (mirror)
rsync -avz --delete /local/dir/ user@hostname:/remote/dir/

# Exclude patterns
rsync -avz --exclude '*.log' --exclude 'node_modules/' \
  /local/dir/ user@hostname:/remote/dir/

# Dry run
rsync -avz --dry-run /local/dir/ user@hostname:/remote/dir/

Security Best Practices

Hardening SSH

# Disable password authentication (edit /etc/ssh/sshd_config)
PasswordAuthentication no
PubkeyAuthentication yes

# Disable root login
PermitRootLogin no

# Change default port
Port 2222

# Restart SSH service
# Linux:
sudo systemctl restart sshd
# macOS:
sudo launchctl stop com.openssh.sshd && sudo launchctl start com.openssh.sshd
# Windows (run in PowerShell as Admin):
Restart-Service sshd

Troubleshooting

Debugging

# Verbose output
ssh -vvv user@hostname

# Check permissions
ls -la ~/.ssh/
# Should be: 700 for ~/.ssh, 600 for keys, 644 for .pub files

Common issues

# Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
chmod 644 ~/.ssh/authorized_keys

# Clear known_hosts entry
ssh-keygen -R hostname

Advanced Operations

Jump hosts (ProxyJump)

# Connect through bastion
ssh -J bastion.example.com [e-mail]

# Multiple jumps
ssh -J bastion1,bastion2 user@final-destination

Multiplexing

# Master connection
ssh -M -S ~/.ssh/control-%r@%h:%p user@hostname

# Reuse connection
ssh -S ~/.ssh/control-user@hostname:22 user@hostname

Execute commands

# Pipe commands
cat local-script.sh | ssh user@hostname 'bash -s'

# With sudo
ssh -t user@hostname 'sudo command'