Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~4 min readLinux
#Linux#SSH#Networking
3D illustration of encrypted SSH tunnel pipes forwarding local and remote TCP ports through a bastion host

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

bash
# 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
sshconfig
# ~/.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
bash
# 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 shell

Key Comparison Table

OptionDirectionSyntaxEnds up listening on
-L local forwardLocal port to remote host-L [bind:]lport:rhost:rportYour machine
-R remote forwardRemote port to local host-R [bind:]rport:lhost:lportThe server
-D dynamic forwardSOCKS proxy-D [bind:]portYour machine
-J jump hostConnection routing-J user@bastionNot a listener
-NNo command-NNot a listener
-fBackground-fNot a listener
ProxyJumpSame as -JConfig directiveNot a listener
LocalForwardSame as -LConfig directiveYour machine
RemoteForwardSame as -RConfig directiveThe server

Practical Edge Cases & Deep Dives

1. Permissions that make SSH refuse the key

bash
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_keys

id_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

sshconfig
Host github.com IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes

Without 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

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

bash
# 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 yes

By 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

bash
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 yes

ForwardAgent 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

bash
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 change

A 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

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

SymptomCauseFix
Permission denied (publickey)Wrong key, or permissions too openssh -v, fix modes to 700/600
"Too many authentication failures"Agent offering every keyIdentitiesOnly yes plus IdentityFile
Password prompt on a key-only serverKey not in authorized_keysssh-copy-id again
Bad owner or permissions on ~/.ssh/configConfig readable by otherschmod 600 ~/.ssh/config
Tunnel connects but nothing answersWrong rhost, or service bound elsewhereCheck ss -ltn on the server
-R tunnel unreachable from outsideGatewayPorts not setDecide deliberately; loopback is safer
Connection drops after idle timeNAT or firewall timeoutServerAliveInterval 60
Host key verification failedServer rebuiltssh-keygen -R host then reconnect
Agent forwarding abusedForwardAgent yes on a jump hostUse ProxyJump
git clone uses the wrong accountIdentitiesOnly missing on Host github.comAdd 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 tools

Small utilities that fit Linux work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Linux guides

More in Linux

All Linux guides

The guides filed next to this one in Linux, in library order.