Appendix D — SSH Cheat Sheet
This is the page you keep open in a second tab. It assumes you have read Chapter 6, SSH, which explains the handshake and why keys beat passwords. Examples use the throwaway lab box: hostname lab, public 203.0.113.10, private 10.0.0.5, admin user ops.
Generate the key pair on your laptop, not on the server. The private key never leaves your machine. The public key is the part you hand out.
ssh-keygen -t ed25519 -C "pipes-lab" -f ~/.ssh/id_ed25519_lab- Set a passphrase. Without one, whoever copies the file owns the key.
ssh-add ~/.ssh/id_ed25519_labloads the decrypted key into your agent, so you type the passphrase once per session.ssh-copy-id -i ~/.ssh/id_ed25519_lab.pub ops@203.0.113.10appends the public key to the server’sauthorized_keys. It asks for a password this one time, and after that you should not need one.
SSH refuses keys it thinks others can read, so permissions matter:
| Path | Mode | Why |
|---|---|---|
~/.ssh/ |
700 | Only you can enter the folder |
~/.ssh/id_ed25519_lab |
600 | Only you can read the private key |
~/.ssh/config, ~/.ssh/known_hosts |
600 | Tampering here can send you somewhere else |
~/.ssh/authorized_keys (server) |
600 | Only the owner decides who gets in |
Fix a folder that has drifted with chmod 700 ~/.ssh and chmod 600 on the files inside it.
The authorized_keys format
Section titled “The authorized_keys format”One key per line: optional restrictions, key type, base64 blob, comment.
from="198.51.100.0/24",no-port-forwarding,no-agent-forwarding ssh-ed25519 AAAA...pipes-labUseful restrictions, written as a comma-separated list with no spaces:
from="198.51.100.0/24"accepts the key only from that network. Home connections often change address or sit behind carrier NAT, so use this only when the address is stable.command="/usr/local/bin/backup.sh"forces one command whatever the client asks for. This is the right shape for a key that exists only to run backups.no-port-forwarding,no-agent-forwarding,no-ptyclose doors you do not need.
Client config: ~/.ssh/config
Section titled “Client config: ~/.ssh/config”Put the nickname here once, and stop typing IP addresses.
Host lab HostName 203.0.113.10 User ops Port 22 IdentityFile ~/.ssh/id_ed25519_lab IdentitiesOnly yesNow ssh lab is the whole command. HostName is the real address; lab is only a nickname. IdentitiesOnly yes offers this one key and nothing else. Without it, your agent offers every key you own, and sshd gives up after a few tries with “Too many authentication failures”.
Defaults for every host go in a Host * block at the bottom:
Host * ServerAliveInterval 60 ServerAliveCountMax 3 AddKeysToAgent yes UseKeychain yesServerAliveInterval 60sends a tiny keep-alive every minute. Gates and NAT boxes forget idle connections, and this keeps yours from being forgotten. A dead link is noticed in about three minutes instead of never.AddKeysToAgent yesloads a key into the agent on first use.UseKeychain yesis macOS-specific: it stores the passphrase in the Keychain. Keep it only on a Mac, because some Linux OpenSSH builds reject the keyword.
ProxyJump: reaching a box with no public address
Section titled “ProxyJump: reaching a box with no public address”Say the worker box has only a private address, 10.0.0.9. The lab box has a public address and can see the private network, so it becomes the bastion.
Host worker HostName 10.0.0.9 User app ProxyJump labssh worker hops through lab, and the inner session is still encrypted end to end. lab carries the bytes but cannot read them. The one-off form is ssh -J lab app@10.0.0.9. Use ProxyJump rather than the older ProxyCommand trick, which you will find in old blog posts.
Server side: sshd_config hardening
Section titled “Server side: sshd_config hardening”Ubuntu 24.04 reads /etc/ssh/sshd_config and then the drop-ins in /etc/ssh/sshd_config.d/. Put your settings in a file that sorts early, such as 10-hardening.conf.
PasswordAuthentication noKbdInteractiveAuthentication noPermitRootLogin noAllowUsers opsMaxAuthTries 3PubkeyAuthentication yes| Line | Effect |
|---|---|
PasswordAuthentication no |
Password logins off. The doorknob rattlers can guess all day and get nowhere. |
KbdInteractiveAuthentication no |
Turns off the PAM prompt, which otherwise brings passwords back through the side door. |
PermitRootLogin no |
Root cannot log in over SSH. Use ops and sudo. |
AllowUsers ops |
A whitelist of accounts. Anything not listed is refused. |
MaxAuthTries 3 |
Authentication attempts allowed per connection. |
Apply it in this order, and keep your current session open the whole time:
sudo sshd -t # syntax check; silent means OKsudo sshd -T | grep -E 'passwordauthentication|permitrootlogin|allowusers'sudo systemctl reload ssh # Ubuntu's unit is "ssh"Host keys and known_hosts
Section titled “Host keys and known_hosts”The first time you connect, SSH shows the server’s host key fingerprint and asks you to confirm it. Your answer is written to ~/.ssh/known_hosts. The warning “REMOTE HOST IDENTIFICATION HAS CHANGED” means the key differs from the one you recorded. Either you rebuilt the server, or someone is between you and it. Do not reach for the delete command until you know which.
ssh-keygen -R 203.0.113.10 # remove the old entry after a rebuild you expectedssh-keygen -lf ~/.ssh/known_hosts # list the fingerprints you have recordedssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub # run on the server, from the provider consoleCompare the last fingerprint with the one you see on the first connection, through a channel that is not SSH. The provider console is that channel. Matching fingerprints mean the box is the one you built.
Forwarding: -L, -R, -D
Section titled “Forwarding: -L, -R, -D”A forward is a tunnel through the SSH connection. Read each one as “port here, through the tunnel, lands there”.
| Flag | Name | In words | Use it when |
|---|---|---|---|
-L 8080:127.0.0.1:3000 |
local | Your laptop’s port 8080 arrives at the server’s localhost port 3000 | The staging app listens only on 127.0.0.1 and you want to look at it |
-R 9000:127.0.0.1:9000 |
remote | The server’s port 9000 arrives at your laptop’s localhost port 9000 | A service on your laptop must be reached by something on the server |
-D 1080 |
dynamic | A SOCKS proxy on your laptop; each app asks the server to dial its destinations | You want a whole browser to exit through the lab box |
ssh -N -L 8080:127.0.0.1:3000 lab # -N: open the tunnel, run no remote commandssh -N -D 1080 labTwo notes. Forwards bind to localhost on your side by default, which is what you want. For -R, the server’s listening address depends on GatewayPorts in its sshd config, so keep it off unless you have a reason to share the port.
File transfer: scp, rsync, sftp
Section titled “File transfer: scp, rsync, sftp”Three tools, three jobs. All of them ride the SSH connection, so your lab alias works with each.
| Tool | Use it for | Example |
|---|---|---|
scp |
One-off copy of a file or folder | scp build.tar.gz lab:/tmp/ |
rsync -avz --progress |
Repeatable sync: skips what has not changed and resumes after a drop | rsync -avz --progress ./site/ lab:/var/www/site/ |
sftp |
Browsing and fiddly multi-file work | sftp lab, then ls, put, get |
Recent OpenSSH releases carry scp over the SFTP protocol, so its old quirks are fading. Reach for rsync for anything you will repeat.
tmux: the session that survives your Wi-Fi
Section titled “tmux: the session that survives your Wi-Fi”A session started over SSH dies with the connection, unless it lives inside tmux (or screen). Start the long job inside tmux, detach, close the laptop, and come back later.
| Command | What it does |
|---|---|
tmux new -s deploy |
Start a named session |
Ctrl-b d |
Detach; the session keeps running |
tmux ls |
List sessions |
tmux attach -t deploy |
Reattach |
tmux kill-session -t deploy |
End it for good |
Ctrl-b is tmux’s default prefix. Press it, let go, then press the next key.
mosh: SSH that survives a change of network
Section titled “mosh: SSH that survives a change of network”mosh keeps your session alive when the laptop changes Wi-Fi, sleeps, or roams between networks. It hands the handshake to SSH, so your config entry still applies, and then talks over UDP.
sudo apt install mosh # on the server, and on your laptopmosh lab # reads your ~/.ssh/config entryThe server needs UDP 60000 to 61000 open in its firewall. Ubuntu’s ufw and any cloud security list both count (see Chapter 14, Firewalls). mosh does not forward ports, so it does not replace ssh -L.
fail2ban: one line to check
Section titled “fail2ban: one line to check”sudo fail2ban-client status sshd # how many addresses are banned right nowThe doorknob-rattlers show up here as a banned count. With PasswordAuthentication no they mostly get nowhere, so fail2ban is tidying up, not your front door. If the command says the jail does not exist, the sshd jail is off.
Tailscale SSH: no port 22 on the internet
Section titled “Tailscale SSH: no port 22 on the internet”If the box is on your tailnet, tailscale ssh ops@lab authenticates you with your tailnet identity, not a key you copied. Depending on your ACL policy, you can close port 22 to the public internet and still reach the box. Keep sshd running for your other clients. The full picture is in Chapter 16, Tailscale.
Troubleshooting: reading ssh -vvv
Section titled “Troubleshooting: reading ssh -vvv”When the error message is not enough, ask the client to narrate. Each extra v adds detail, and three of them show the authentication steps.
ssh -vvv lab 2>&1 | lessRead from the top, and stop at the first line that surprises you. A healthy key login looks roughly like this, trimmed:
debug1: Connecting to 203.0.113.10 [203.0.113.10] port 22.debug1: Connection established.debug1: Authenticating to 203.0.113.10:22 as 'ops'debug1: Offering public key: /home/you/.ssh/id_ed25519_lab ED25519 SHA256:...debug1: Authentications that can continue: publickeydebug1: Server accepts key: /home/you/.ssh/id_ed25519_lab ED25519 SHA256:...debug1: Authentication succeeded (publickey).| Line you see | What it means | Where to look |
|---|---|---|
Connecting to ... port 22 |
The client is starting. A wrong address shows up here first. | HostName in ~/.ssh/config |
Connection timed out |
Packets go out and nothing comes back. | Cloud firewall and ufw (Chapter 14) |
Connection refused |
The address answered, but nothing listens on that port. | sudo systemctl status ssh on the server |
Offering public key |
The client is trying this key. Unfamiliar keys mean the agent is talking. | IdentitiesOnly yes |
Server accepts key |
The key is in authorized_keys. Good news. |
If login still fails, check the user and the shell |
Permission denied (publickey) |
The server refused every key offered. | File owner, mode 600, and the authorized_keys format |
Too many authentication failures |
The agent offered too many keys before the right one. | IdentitiesOnly yes in the Host block |
REMOTE HOST IDENTIFICATION HAS CHANGED |
The host key differs from your known_hosts record. |
Verify the fingerprint from the console first |
The client tells you the path it took. The server tells you why it said no.
Where to go next
Section titled “Where to go next”- Appendix E, Common errors lists the messages you will meet outside SSH, with the fix for each.
- Appendix F, Hardening checklist turns the sshd settings above into a server-wide list.
- Appendix G, Glossary defines the terms this page assumes.
- Chapter 6, SSH explains the handshake behind every line in this sheet.
Keep one session open, change one thing at a time, and check with sshd -T before you trust the file. That habit has saved more lab boxes than any clever trick.
Book 2 of a series. Book 1: The Glue.