v1.0 to v1.0

---

name: ssh-remote

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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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:

```bash

# 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.

```bash

# 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.

```bash

# 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

```bash

# 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)

```bash

# 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

```bash

# 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.

```bash

# 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

```bash

# 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.

```bash

# 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