Linux SSH Mastery: Key Auth, ~/.ssh/config, and Local/Remote Port Forwarding
Ed25519 keys, a config file that ends flag memorisation, and the -L, -R and -D tunnels that reach services bound to localhost.

Quick Summary
OpenSSH authentication rests on a key pair: a private key that never leaves the machine and a public key that is appended to ~/.ssh/authorized_keys on the server. ssh-keygen -t ed25519 creates the pair, ssh-copy-id installs the public half, and the server accepts the connection if the client can sign a challenge with the matching private key. Passwords are then optional, and usually disabled.
The part that turns SSH from workable into pleasant is ~/.ssh/config. Host aliases, per-host users and ports, key selection, jump hosts, keepalive — all of it is configuration rather than memorised flags, and it applies to scp, rsync, git, and anything else built on the same client.
Port forwarding is the same connection doing a second job. -L exposes a remote service on a local port, -R exposes a local service on a remote port, and -D turns the connection into a SOCKS proxy. These are the tools for reaching a database that only listens on localhost, and for letting a remote machine call back into yours.
Basic Syntax & Signature
# Generate an Ed25519 key with no passphrase for automation, or with one for humans
ssh-keygen -t ed25519 -a 100 -C "deploy@laptop" -f ~/.ssh/id_ed25519
ssh-keygen -t ed25519 -C "laptop" -f ~/.ssh/id_work
# Install the public key on the server
ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@203.0.113.10
# First connection: verify and record the host key
ssh -o StrictHostKeyChecking=accept-new deploy@203.0.113.10# ~/.ssh/config (chmod 600)
Host *
ServerAliveInterval 60
ServerAliveCountMax 3
AddKeysToAgent yes
IdentitiesOnly yes
Host api-prod
HostName 203.0.113.10
User deploy
Port 2222
IdentityFile ~/.ssh/id_prod
IdentitiesOnly yes
ForwardAgent no
Host db-internal
HostName 10.0.4.15
User ubuntu
ProxyJump api-prod
LocalForward 5433 127.0.0.1:5432
Host bastion
HostName bastion.example.com
User jump
IdentityFile ~/.ssh/id_bastion
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
IdentitiesOnly yes# Port forwarding
ssh -L 5433:127.0.0.1:5432 deploy@203.0.113.10 -N
ssh -N -L 8080:internal-service:80 bastion
ssh -R 9000:127.0.0.1:3000 deploy@203.0.113.10
ssh -D 1080 -N deploy@203.0.113.10
ssh -v deploy@host # debug key selection
ssh -T git@github.com # test GitHub auth without a shellKey Comparison Table
| Option | Direction | Syntax | Ends up listening on |
|---|---|---|---|
-L local forward | Local port to remote host | -L [bind:]lport:rhost:rport | Your machine |
-R remote forward | Remote port to local host | -R [bind:]rport:lhost:lport | The server |
-D dynamic forward | SOCKS proxy | -D [bind:]port | Your machine |
-J jump host | Connection routing | -J user@bastion | Not a listener |
-N | No command | -N | Not a listener |
-f | Background | -f | Not a listener |
ProxyJump | Same as -J | Config directive | Not a listener |
LocalForward | Same as -L | Config directive | Your machine |
RemoteForward | Same as -R | Config directive | The server |
Practical Edge Cases & Deep Dives
1. Permissions that make SSH refuse the key
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519 ~/.ssh/config
chmod 644 ~/.ssh/id_ed25519.pub ~/.ssh/authorized_keys ~/.ssh/known_hosts
# Server-side checks
sshd -T | grep -E 'permitrootlogin|passwordauthentication|pubkeyauthentication'
stat -c '%a %U:%G %n' /home/deploy/.ssh /home/deploy/.ssh/authorized_keysid_ed25519 readable by group or other is rejected, and ~/.ssh writable by group means the server refuses to use authorized_keys unless StrictModes no is set — which is the wrong fix. The common server-side failure is a home directory owned by the wrong user after a restore from backup, which also breaks the check.
2. Selecting the right key with IdentitiesOnly
Host github.com
IdentityFile ~/.ssh/id_ed25519_github
IdentitiesOnly yesWithout IdentitiesOnly, the client offers every key the agent holds, and a server with a low MaxAuthTries (default 6) disconnects before reaching the correct one. GitHub's own documentation recommends IdentitiesOnly yes for this reason: "Too many authentication failures" is almost always an agent with a dozen keys and no IdentityFile to focus it.
3. Reaching a database that only listens on localhost
# The database binds 127.0.0.1:5432 on the server; nothing else can reach it.
ssh -N -L 5433:127.0.0.1:5432 deploy@203.0.113.10
psql -h 127.0.0.1 -p 5433 -U app -d appdb
# Equivalent through a jump host in one connection
ssh -J deploy@bastion -N -L 5433:db-internal:5432 deploy@prod-api-N skips the remote command so the session exists only to forward. Without -f, the terminal stays attached, which is what you want when debugging and not what you want in a startup script. -L binds to loopback by default; -L 0.0.0.0:5433:... exposes the tunnel to your whole network, which is rarely intended.
4. Remote forward for webhooks and callbacks
# Make the local dev server reachable from the server on port 9000
ssh -N -R 9000:127.0.0.1:3000 deploy@203.0.113.10
# The server side must allow it
# /etc/ssh/sshd_config
# GatewayPorts no (bind to loopback only)
# AllowTcpForwarding yesBy default the remote listener binds to 127.0.0.1 on the server, so a webhook sender on the internet still cannot reach it. Opening GatewayPorts exposes the tunnel to the network and is a real access-control decision, not a convenience toggle — the tunnel bypasses the firewall rules the server was configured with.
5. Key management with an agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_prod
ssh-add -l
# macOS: store in the Keychain once
ssh-add --apple-use-keychain ~/.ssh/id_prod
# Persist across sessions through the config
# Host *
# AddKeysToAgent yesForwardAgent yes is convenient and dangerous: anyone with root on the intermediate host can use the forwarded socket to authenticate as you anywhere the key is accepted. ProxyJump gives the same reachability without forwarding the agent, and is the reason it replaced nested ssh -t host ssh host2 chains.
6. Verifying a host key change
ssh-keygen -F 203.0.113.10 # look up the recorded key
ssh-keygen -R 203.0.113.10 # remove a stale entry
ssh-keyscan -t ed25519 203.0.113.10 # fetch the current key
ssh -o StrictHostKeyChecking=accept-new host # accept a new key once, refuse on changeA host key mismatch is either a rebuilt server or a man in the middle; the client refuses either way, and -o StrictHostKeyChecking=no disables the only warning that distinguishes them. Removing a stale entry by hand in known_hosts also works, and is the honest way to handle a re-provisioned instance.
7. The same config for scp, rsync, and sftp
# Host aliases apply everywhere the SSH client is used
scp deploy@api-prod:/srv/app/release.tar.gz ./
rsync -avz --delete ./dist/ api-prod:/srv/app/dist/
sftp db-internal
# rsync over a jump host without spelling out the tunnel
rsync -avz -e 'ssh -J bastion' ./backup/ deploy@10.0.4.15:/srv/backup/
# Compression and progress for a slow link
tar czf - ./data | ssh api-prod 'tar xzf - -C /srv/data'Because scp and rsync call the SSH client, ~/.ssh/config is the single place to define host, user, port, and key — a script using api-prod:/path needs no connection flags at all. tar over ssh is often faster than scp -r for many small files, because it sends one stream instead of one request per file.
Common Compilation/Runtime Mistakes
| Symptom | Cause | Fix |
|---|---|---|
Permission denied (publickey) | Wrong key, or permissions too open | ssh -v, fix modes to 700/600 |
| "Too many authentication failures" | Agent offering every key | IdentitiesOnly yes plus IdentityFile |
| Password prompt on a key-only server | Key not in authorized_keys | ssh-copy-id again |
Bad owner or permissions on ~/.ssh/config | Config readable by others | chmod 600 ~/.ssh/config |
| Tunnel connects but nothing answers | Wrong rhost, or service bound elsewhere | Check ss -ltn on the server |
-R tunnel unreachable from outside | GatewayPorts not set | Decide deliberately; loopback is safer |
| Connection drops after idle time | NAT or firewall timeout | ServerAliveInterval 60 |
Host key verification failed | Server rebuilt | ssh-keygen -R host then reconnect |
| Agent forwarding abused | ForwardAgent yes on a jump host | Use ProxyJump |
git clone uses the wrong account | IdentitiesOnly missing on Host github.com | Add IdentityFile for the account |
The configuration file is the difference between SSH as a set of flags to memorise and SSH as a documented inventory of who connects where with which key. Writing it once, with IdentitiesOnly and a Host * block for keepalive, removes most of the failure modes above before they happen, and makes the remaining ones diagnosable with a single -v.
Try matching browser tools
All toolsSmall utilities that fit Linux work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Linux guides
All Linux guidesBash Indexed Arrays, Associative Maps, and Parameter Expansion
Quoting decides whether an array stays a list, and the expansion operators replace most external text tools. Includes set -u, mapfile, namerefs, and the bash 3.2 differences that break scripts on macOS.
Parsing JSON and YAML in Shell Pipelines with jq and yq
jq is a filter language, not a pretty-printer. The operators that do the work, --arg versus string interpolation, in-place YAML edits, and how to tell which yq is installed before writing a command.
Linux Memory, Swap, the OOM Killer, vmstat, and sysctl Tuning
MemAvailable versus used, the vmstat columns that prove thrashing, how the OOM killer picks its victim, and the sysctl keys that belong in /etc/sysctl.d instead of a one-off command.
Linux Firewalls: ufw, iptables, and nftables Rules and Persistence
First-match ordering, stateful filtering, and persistence: the three ideas behind every Linux firewall. Plus why Docker-published ports ignore ufw and how DOCKER-USER closes them.
More in Linux
All Linux guidesThe guides filed next to this one in Linux, in library order.