Skip to content

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.

Terminal window
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_lab loads 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.10 appends the public key to the server’s authorized_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.

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-lab

Useful 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-pty close doors you do not need.

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 yes

Now 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 yes
  • ServerAliveInterval 60 sends 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 yes loads a key into the agent on first use.
  • UseKeychain yes is 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 lab

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

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 no
KbdInteractiveAuthentication no
PermitRootLogin no
AllowUsers ops
MaxAuthTries 3
PubkeyAuthentication 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:

Terminal window
sudo sshd -t # syntax check; silent means OK
sudo sshd -T | grep -E 'passwordauthentication|permitrootlogin|allowusers'
sudo systemctl reload ssh # Ubuntu's unit is "ssh"

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.

Terminal window
ssh-keygen -R 203.0.113.10 # remove the old entry after a rebuild you expected
ssh-keygen -lf ~/.ssh/known_hosts # list the fingerprints you have recorded
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub # run on the server, from the provider console

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

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
Terminal window
ssh -N -L 8080:127.0.0.1:3000 lab # -N: open the tunnel, run no remote command
ssh -N -D 1080 lab

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

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.

Terminal window
sudo apt install mosh # on the server, and on your laptop
mosh lab # reads your ~/.ssh/config entry

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

Terminal window
sudo fail2ban-client status sshd # how many addresses are banned right now

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

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.

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.

Terminal window
ssh -vvv lab 2>&1 | less

Read 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: publickey
debug1: 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.

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.