Remote
SSH & File Transfer — keys, tunnels, scp, rsync, sftp
Set up key-only SSH, aliases and bastion hops in ~/.ssh/config, then move files the right way: scp for one-shot copies, rsync for repeatable syncs (always dry-run first), sftp for interactive browsing — including a transfer through a jump host.
Quick reference — reach for these first
ssh-keygen -t ed25519 -C "USER@HOST"Ed25519 is small, fast and preferred over RSA; add -a 100 to slow brute-force of the passphrase.ssh-copy-id -i ~/.ssh/id_ed25519.pub USER@HOSTAppends the public key to the server's ~/.ssh/authorized_keys with correct perms — never copy the private key.ssh -J USER@BASTION USER@HOSTProxyJump hops through the jump host without landing files or keys on it; chain more with commas.rsync -avzn --delete SRC/ USER@HOST:DST/-n/--dry-run lists what WOULD change; read it before dropping -n, especially with --delete.scp -r SRC USER@HOST:DSTSimple recursive one-shot copy; no resume and no delta — use rsync for anything you repeat.A file transfer hopping through a bastion
Text equivalent: Your laptop connects to an internal target server by hopping through a bastion host. SSH keys and ProxyJump live only on the laptop; the bastion just forwards the encrypted connection, so no files or keys land on it. scp, rsync and sftp all ride the same hop.
Common tasks
Set up keys & config · Transfer files · Verify & harden
| Set up keys & config | Transfer files | Verify & harden |
|---|---|---|
| Generate an Ed25519 keypair with a passphrase | ssh-keygen -t ed25519 -a 100 -C "USER@HOST" | ls -l ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.pub shows both files; private key is -rw------- (600). |
| Load the key into the agent for the session | eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519 | ssh-add -l lists the key's fingerprint. |
| Install the public key on the server | ssh-copy-id -i ~/.ssh/id_ed25519.pub USER@HOST | ssh USER@HOST true connects without a password prompt. |
| Lock down local ~/.ssh permissions | chmod 700 ~/.ssh && chmod 600 ~/.ssh/* && chmod 644 ~/.ssh/*.pub | ssh -v USER@HOST no longer warns about unprotected key files. |
| Add a Host alias and bastion hop to ~/.ssh/config | printf 'Host app\n HostName HOST\n User USER\n ProxyJump USER@BASTION\n IdentityFile ~/.ssh/id_ed25519\n' >> ~/.ssh/config | ssh app lands on HOST, having transparently hopped through BASTION. |
| Verify the hop works end to end | ssh app hostname | Output is HOST's hostname, not the bastion's. |
| Dry-run an rsync before touching the target | rsync -avzn SRC/ app:DST/ | Transcript lists files to send and ends with a 'DRY RUN' total; no bytes actually moved. |
| Run the real rsync with progress | rsync -avz --progress SRC/ app:DST/ | Per-file percentages scroll; final line reports sent/received byte totals. |
| Resume a large transfer that was interrupted | rsync -avz --partial --progress SRC/big.iso app:DST/ | Re-run picks up from the partial file instead of restarting at 0%. |
| [DESTRUCTIVE — PROD] Mirror a dir, deleting extras on the target | rsync -avzn --delete SRC/ app:DST/ # confirm, THEN drop -n | Dry-run shows exactly which 'deleting …' lines will occur; only then re-run without -n. |
| Copy a single directory with scp (no sync) | scp -r SRC app:DST | ssh app ls DST shows the copied tree. |
| Browse and pull files interactively with sftp | sftp app | At the sftp> prompt, ls, cd, get FILE and put FILE all work; bye exits. |
| Verify integrity after transfer | ssh app 'sha256sum DST/FILE' && sha256sum SRC/FILE | Both checksums match; du -sh on each side reports the same size. |
| Confirm the server is key-only (hardening reminder) | ssh app 'sudo sshd -T | grep -E "passwordauthentication|pubkeyauthentication"' | Reports passwordauthentication no and pubkeyauthentication yes. |
Copy a directory to a server that sits behind a bastion
jump-host rsync with dry-run first
cat >> ~/.ssh/config <<'EOF'
Host app
HostName 10.0.1.42
User deploy
ProxyJump deploy@bastion.example.com
IdentityFile ~/.ssh/id_ed25519
EOF
# alias 'app' now hops bastion.example.com -> 10.0.1.42ssh app hostname
# app-prod-1 (the internal host, not the bastion)rsync -avzn --delete ./site/ app:/var/www/site/
# sending incremental file list
# index.html
# assets/app.css
# deleting assets/old.css
# (DRY RUN) sent 1,204 bytes ...rsync -avz --progress --delete ./site/ app:/var/www/site/
# index.html 12,044 100% ...
# sent 48,903 bytes received 412 bytes ...ssh app 'sha256sum /var/www/site/index.html; du -sh /var/www/site' && sha256sum ./site/index.html && du -sh ./site
# e3b0c442... index.html (matches local)
# 4.2M /var/www/site == 4.2M ./siteTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| Permission denied (publickey) | ssh -v app 2>&1 | grep -iE 'offering|identity|permission' and ssh-add -l | Whether the client even offered your key, and whether it is loaded in the agent. | If no key offered: ssh-add the key or set IdentityFile. If offered but rejected: on the server check ~/.ssh is 700 and authorized_keys is 600, owned by the user, and the pubkey line is present. |
| WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED | Confirm out-of-band (rebuild, new IP, or provider notice) that the host key legitimately changed — do NOT blindly clear it. | Whether this is a benign re-provision or a possible man-in-the-middle. | If legitimate: ssh-keygen -R HOST to drop the stale known_hosts entry, then reconnect and accept the new key. If unexpected: stop and investigate before trusting the host. |
| Connection times out vs. connection refused | nc -vz HOST 22 (or ssh -v) and note which message you get. | Timed out = packets dropped (firewall / security group / wrong IP / host down). Refused = reached the host but nothing is listening on that port. | Timed out: open port 22 in the firewall/security group or fix the address. Refused: start sshd, or connect to the real port via Port in ~/.ssh/config. |
| rsync --delete removed far more than expected | Re-run the exact command with -n added and read every 'deleting …' line. | That a trailing-slash mismatch or wrong SRC made rsync treat the target as a mirror of an almost-empty source. | Fix the source path and trailing slashes (SRC/ copies contents; SRC copies the dir itself). Never run --delete without a clean dry-run; restore lost files from backup/snapshot. |
| Transfer is far slower than the link should allow | Compare rsync -avz vs -av (drop -z) on already-compressed data, and check CPU with top during the run. | Whether gzip (-z) is the bottleneck on incompressible files, or the cipher/CPU is. | Drop -z for media/archives; for big LAN moves pick a faster cipher (ssh -c aes128-gcm@openssh.com) or raise rsync -e 'ssh -T'. Test with --dry-run excluded. |
| Key works manually but agent/ProxyJump fails in scripts | env | grep SSH_AUTH_SOCK inside the failing context and ssh-add -l there. | Whether the agent socket is actually inherited by that shell/cron/CI environment. | Export SSH_AUTH_SOCK into the environment, or use IdentityFile in ~/.ssh/config so the key is found without the agent. Avoid relying on agent forwarding to the bastion — ProxyJump needs the key only on the client. |
References
- ssh(1) — OpenSSH client manual (ProxyJump, -J, -c)man.openbsd.org
- ssh_config(5) — Host, ProxyJump, IdentityFileman.openbsd.org
- ssh-keygen(1) — key generation and known_hosts removalman.openbsd.org
- rsync(1) — official man page (-a -v -z --delete --dry-run --partial)download.samba.org
- scp(1) — OpenSSH secure copyman.openbsd.org
OpenSSH 8.x+ client/server, rsync 3.x on both ends, and a POSIX shell. USER, HOST, BASTION, SRC and DST are placeholders — substitute your own. Examples assume you have shell access and sudo on the target only where noted.