SSH Cheat Sheet

ssh user@host                           # connect
ssh -p 2222 user@host                   # non-standard port
ssh-keygen -t ed25519 -C "you@laptop"   # create a key pair
ssh-copy-id user@host                   # install your public key on the server
scp file.txt user@host:/tmp/            # copy a file to the server
ssh -L 8080:localhost:80 user@host      # local port forward (tunnel)

This page covers the OpenSSH client and server shipped by every major distro. For a step-by-step setup of key login and disabling passwords, read how to set up SSH keys. If a connection fails, jump to troubleshooting.

Connecting

Keys and the agent

Copying files

Port forwarding and tunnels

Client config: ~/.ssh/config

Settings here apply automatically, so ssh web1 replaces a long command line. The first value found for each option wins, so put specific Host blocks before Host *.

Host web1
    HostName 203.0.113.10
    User deploy
    Port 2222
    IdentityFile ~/.ssh/work_ed25519
    IdentitiesOnly yes

Host internal-*
    ProxyJump bastion

Host *
    AddKeysToAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Server side (sshd)

Put changes in a drop-in such as /etc/ssh/sshd_config.d/50-local.conf instead of editing the main file. Always keep a working session open while you test.

On Ubuntu 22.10 and later, sshd is started by ssh.socket. If you change Port, run sudo systemctl daemon-reload and sudo systemctl restart ssh.socket so the socket listens on the new port. On Fedora with SELinux, a new port also needs sudo semanage port -a -t ssh_port_t -p tcp 2222. More on unit names in the systemctl cheat sheet.

Troubleshooting connections

Common recipes

Run a long job that survives disconnects (see the tmux cheat sheet):

ssh -t user@host 'tmux new -A -s main'

Open a remote web admin panel that only listens on the server's localhost:

ssh -N -L 9090:localhost:9090 admin@server
# then browse to http://localhost:9090

Run the same command on several servers:

for h in web1 web2 db1; do
    echo "== $h"; ssh "$h" 'uptime'
done

Copy your public key manually when ssh-copy-id is not available:

cat ~/.ssh/id_ed25519.pub | ssh user@host 'mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

Back up a remote database straight to your machine:

ssh db1 'sudo -u postgres pg_dump mydb | gzip' > mydb-$(date +%F).sql.gz

Compare a remote file with a local one:

diff <(ssh web1 cat /etc/nginx/nginx.conf) /etc/nginx/nginx.conf

Gotchas

• -p vs -P. ssh uses lowercase -p for the port; scp and sftp use uppercase -P (lowercase -p means "preserve times").
• Service name differs. The unit is ssh on Debian/Ubuntu/Mint and sshd on Fedora/Arch/openSUSE. The package to install is openssh-server (apt, dnf, zypper) or openssh (pacman).
• Permissions are strict. sshd ignores authorized_keys if your home, ~/.ssh or the file is writable by others. Private keys must be 600 or the client refuses them.
• Too many keys. With many keys in the agent, the server may disconnect with "Too many authentication failures" before the right key is tried. Use IdentitiesOnly yes with IdentityFile.
• scp uses SFTP now. Current OpenSSH scp transfers over the SFTP protocol. Remote paths with spaces need only normal quoting; scp -O forces the legacy protocol for very old servers.
• Agent forwarding is a risk. Anyone with root on the remote host can use your forwarded agent. Prefer ProxyJump (-J) for hopping through bastions.
• Lockout risk. Test with sshd -t and a second session before closing the first one after any change to sshd or the firewall.

Reference: ssh(1) and ssh_config(5) in the OpenBSD manual pages (OpenSSH upstream).

Frequently asked questions